From 48178428b7c63dce49c75dd720dff1ec9270cb39 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Mon, 8 Oct 2018 16:40:28 +0200 Subject: [PATCH 01/18] Remove existing client --- README | 4 - setup.cfg | 2 - setup.py | 34 ------- signrequest_client/__init__.py | 8 -- signrequest_client/client.py | 146 ------------------------------ tests/SignRequestDemoDocument.pdf | Bin 31191 -> 0 bytes tests/__init__.py | 1 - tests/test_client.py | 48 ---------- 8 files changed, 243 deletions(-) delete mode 100644 README delete mode 100644 setup.cfg delete mode 100644 setup.py delete mode 100644 signrequest_client/__init__.py delete mode 100644 signrequest_client/client.py delete mode 100644 tests/SignRequestDemoDocument.pdf delete mode 100644 tests/__init__.py delete mode 100644 tests/test_client.py diff --git a/README b/README deleted file mode 100644 index 8390967..0000000 --- a/README +++ /dev/null @@ -1,4 +0,0 @@ -signrequest-python-client -========================= - -**WARNING:** Not officially supported, use at your own risk. diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 5e40900..0000000 --- a/setup.cfg +++ /dev/null @@ -1,2 +0,0 @@ -[wheel] -universal = 1 diff --git a/setup.py b/setup.py deleted file mode 100644 index 232179b..0000000 --- a/setup.py +++ /dev/null @@ -1,34 +0,0 @@ -# -*- coding: utf-8 -*- -__author__ = "Michaël Krens" -__copyright__ = "Copyright 2015, SignRequest B.V." - -import os -from setuptools import setup - -from signrequest_client import __version__ as version - - -def read(fname): - return open(os.path.join(os.path.dirname(__file__), fname)).read() - -# helpfull: https://hynek.me/articles/sharing-your-labor-of-love-pypi-quick-and-dirty/ -# distribute using: python setup.py sdist bdist_wheel upload - -setup( - name="signrequest-python-client", - version=version, - author="Michaël Krens", - author_email="michael@signrequest.com", - description="A python client to use the SignRequest REST api", - keywords="signrequest sign request", - url="https://github.com/SignRequest/signrequest-python-client", - packages=['signrequest_client'], - long_description=read('README'), - classifiers=[ - "Development Status :: 3 - Alpha", - "Topic :: Utilities", - ], - install_requires=[ - "requests", - ], -) diff --git a/signrequest_client/__init__.py b/signrequest_client/__init__.py deleted file mode 100644 index 59793c0..0000000 --- a/signrequest_client/__init__.py +++ /dev/null @@ -1,8 +0,0 @@ -# -*- coding: utf-8 -*- -__author__ = 'Michaël Krens' -__copyright__ = "Copyright 2015, SignRequest B.V." -__version__ = '0.0.8' - -from .client import SignRequestClient, SignRequestClientException - -__all__ = ['SignRequestClient', 'SignRequestClientException'] diff --git a/signrequest_client/client.py b/signrequest_client/client.py deleted file mode 100644 index a48e11e..0000000 --- a/signrequest_client/client.py +++ /dev/null @@ -1,146 +0,0 @@ -# -*- coding: utf-8 -*- -import hashlib -import hmac -from signrequest_client import __version__ as version - -__author__ = "Michaël Krens" -__copyright__ = "Copyright 2015, SignRequest B.V." -import json -try: - import requests -except ImportError: - pass - - -class SignRequestClientException(Exception): - pass - - -class SignRequestClient(object): - - def __init__(self, subdomain, token=None, api_base_endpoint='https://signrequest.com/api/v1/', - username=None, password=None): - self.subdomain = subdomain - self.token = token - self.api_base_endpoint = api_base_endpoint - if username and password: - self.authenticate(username, password) - if not self.token: - raise SignRequestClientException( - "Please authenticate by providing a valid token or by username and password") - - def get_headers(self, is_json=False): - headers = {'Authorization': 'Token %s' % self.token, 'X-Client-Version': version} - if is_json: - headers['Content-Type'] = 'application/json' - return headers - - def authenticate(self, username, password): - resp = requests.post( - self.api_base_endpoint + 'api-tokens/', - data={'subdomain': self.subdomain}, auth=(username, password) - ) - if resp.ok: - self.token = json.loads(resp.content)['token'] - else: - raise SignRequestClientException("Could not authenticate, response: %s " % resp.content) - return self.token - - def create_document_from_file(self, file_object): - resp = requests.post( - self.api_base_endpoint + 'documents/', files={'file': file_object}, - headers=self.get_headers()) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not create document, response: %s " % resp.content) - - def create_document_from_url(self, url): - resp = requests.post( - self.api_base_endpoint + 'documents/', data={'file_from_url': url}, - headers=self.get_headers(is_json=True)) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not create document, response: %s " % resp.content) - - def create_signrequest(self, uuid, from_email, signers=None, who='o', message='', subject='', - required_attachments=None, disable_attachments=False, disable_text=False): - signers = signers or [] - required_attachments = required_attachments or [] - if not isinstance(signers, list): - raise SignRequestClientException("`signers` must be a list") - if not isinstance(required_attachments, list): - raise SignRequestClientException("`required_attachments` must be a list") - # all other invalid posts will be returned by the API with an error - data = { - 'document': self.api_base_endpoint + 'documents/' + uuid + '/', - 'from_email': from_email, - 'who': who, - 'message': message, - 'subject': subject, - 'disable_attachments': disable_attachments, - 'disable_text': disable_text, - 'required_attachments': required_attachments, - 'signers': signers, - } - resp = requests.post( - self.api_base_endpoint + 'signrequests/', - data=json.dumps(data), - headers=self.get_headers(is_json=True)) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not create document, response: %s " % resp.content) - - def resend_signrequest_email(self, signrequest_uuid): - resp = requests.post( - self.api_base_endpoint + 'signrequests/' + signrequest_uuid + '/resend_signrequest_email/', - headers=self.get_headers()) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not resend email, response: %s " % resp.content) - - def get_document(self, uuid): - resp = requests.get( - self.api_base_endpoint + 'documents/' + uuid + '/', - headers=self.get_headers()) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not get document, response: %s " % resp.content) - - def get_documents(self, filter_params=''): - filter_params = filter_params.strip('?').strip('&') - endpoint = self.api_base_endpoint + 'documents/?' + filter_params - resp = requests.get( - endpoint, - headers=self.get_headers()) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not get documents, response: %s " % resp.content) - - def get_events(self, doc_uuid=None, filter_params=''): - endpoint = self.api_base_endpoint + 'events/' - filter_params = filter_params.strip('?').strip('&') - if doc_uuid or filter_params: - endpoint += '?' - if filter_params: - endpoint += filter_params - if doc_uuid: - if not endpoint.endswith('?'): - endpoint += '&' if not endpoint.endswith('&') else '' - endpoint += 'document__uuid=' + doc_uuid - resp = requests.get( - endpoint, - headers=self.get_headers()) - if resp.ok: - return json.loads(resp.content) - else: - raise SignRequestClientException("Could not get event(s), response: %s " % resp.content) - - def confirm_callback_authenticity(self, event_time, event_type, event_hash): - return event_hash == hmac.new(self.token, (event_time + event_type), - hashlib.sha256).hexdigest() diff --git a/tests/SignRequestDemoDocument.pdf b/tests/SignRequestDemoDocument.pdf deleted file mode 100644 index be8fdb18a2f26d432d9234d5316eb93f55015fe2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 31191 zcmeFZ1#le8k|;VO$zmp3%*+}wvn*z2W@fZ(i<#MCW@gD2Gc#Ju%(Cdo=bXFu?!Mi9 z3lV?c|M9z{yR(uiE4wNSdTPkzMa1Zs=viRNy7Ri*x*NJPVVMaT3GECmVR?8Mq)lwi zoXrVAZx}@eF$-&F6GsLyYXfH!5fdXjV-r3;SSM#k69XGq_w;r(DXSGm$ReQkB| z+(rYGvOC}jUDbr}elY`O9$EACnHvj9xk+Wa%hUvfu~wpK$Ajs0gjxfkFT0%3=67&1 z@4}v|`Q0t<3(&aa#Z&vic!XNhjMS{_=9B2kHvvDiJv$^V7{%U*B}qD&mHqNM6asDk z@@t2$Mp+uE`{su4`M>eA^gB86UjWA%TU>J%V15Pf5!7Zl?U($vGl^nM}Xe78}Z@hznZE0|FfGf?03KBQ5TsLTl)zwOtD#1jz9Ds+S zCSX)yx%Br{Ovr|mH+&C|TG((jaoCgNi%^=7|2gs1L$|c#uCZ8osos+9x(k04#$&mwobsQFcd7WIYI`~zD`D`IPB_+L|t`g$&bQ&*vp;a`AY{OzWn$qmZC zd@gw%VYbK!O&0rJzLo6 zNe!!22XAas{MaSuWoobfMuh@6WK{0k zzqes!4|@{^bvZ*z6C-B^B^N{I-)RXO12Yo_H4Edn*3H7fNXYQf#KO$nnUI-{laN8k z!r4jQ#8KGJ#@^1>#MYURgOEYk&f3mV$=<-ogh9l_)xyX`QC#S65kW*)`OkRpw|K$C z%EZq2_u%ll@VWuC7In8U1ps7Z0Mq~g02%-Z#0I>3gMe?BDiG(NU|k?30Q?U;7ytl< z_80ud^(7hbh5-=0U8d=2f5@%8!NG6W@8jd!^;_2;Pf8;yLTM8_TLVX9J7!i^LT^Hm z-(kwh*}}$z-pI}d05AtQzn%5~E&#*Z>GsD-4=@He0!#n~02_eQ8`a|NX#$`J7y<0w zAcjA1c5f*w0No!n1Ay5Zoep6ACSm`^Z})bmd*ieN*uK$!rybwY&Tmx1Hy)EW=ufKQ z8})bkx0c_!ZQmfbH;aDD{Kh)HVSn3U@(0EB?P>H++DzW^aQZ{i=1uSK{6PR#0Q=j? z@&+*jnBH9QdII<;Z*J#o=VWeYPY9xC1aJsR$Us26kpKW%Trg(<;s41&xWAnbfOuU7 z2m^rs&EvO{|E3Bc@bw1(1saF|Tn7iD0Kiay;3&Y?9st4HD+hwV1O9&Te;u$;&~QL7 za7Y-4cW(?X$N&HY1P}}w6$K6n2Ie=<8xi6iBos6Z3M?ubHW8D05;_JZ2dAKdvWl8} zOnh?V^xXV=EMkzVhJlmY=h(#RnyHytHg-jaxa`{chK2JFBxDqn%);W1F0KiklN+S0 zLSlv{X1#qZq90Aooxc=byk-00&+`7wra!U;2ZMN{Frd6y41|D&1P6fsWi=25jLBdU zl}J#*Att*T9F6(&#`%}d3t~k>$JZqQ{2Ln>3OEXYACURu9~J)p@c(N(fJDw5VN&@6 zU#e;G9Vo;rfitZ6hNl|sfh@JYZu6)${h6gHC>y8P)G;SnVq3W^l$si!7+(cXZAKBF zfER{Qly77@pcXs;iTq|Kh5Q+8i{E3|ZmS1eS0mPLf*y32-tfXB!1{k732G577jIAr zVg~KPbq`0rY$UshP4`$PuCa_24^p-nsZ-vT+e<#U$VR77V|GC)!m_++EmJmt^h?$< zFJ^~SX(=8kaXP+&c4KQNIzpTihOMrSmiq$PmiNc0h!8pKnKaDYMurky&%tOun*)3? zl_q*UagVYpofDrNl8}1NT1DJNDtbC+pFxG$;Ksfby4LKJFGwgZh+~9xz#q`UoG0M zL$Sp|#o-j*tvw#sJ&{P+Seo}_8bE>QkZhH5>F$Zzi+SUm89tG>F$O~TFPIWl04LHJ zS3*sXjrD*@PG;S4Wy8%BSy%Hh_#-KuNP>t6h^h&VDlNQDyik)+pM+S3)Od!wbR_O~ zF`{gaZSLya;~JcIHmYxCVmGx)%7ebe%{a2_uqj{D3Y#OL@(fSc-5K~lNdWIqSwg^7n~$}`&n$He*F0Fs zSW#M$QjllD#IH1Ih7bCJNE2{=6i}w_N`zez9kM^$BVs9CGgew$=O1mq-2U#AxO~)r zyfp9ru1?Zd1KAr5x|Ki=4Gqg#2oc|aA((VN1Y}8#)teW^iDQ?a6l+`%+#8ZN#|Agc z3-@ks%%eKMs@7~_-1JELp;_ZfEl=a2IgIg0)=gZyFLe%XvK4mjj9t^+6WghUYZv?f zRs_$;kX|fv+hDnvX3JE0yR*-ne+z5)Wn{qTLdujAGBong*y+%sdp4rQdSM=0E_|xM zwZNHF5t4AO#FgoefO6V}Mo@grQ;`7?lx?_mI z)95%nY^g*4BotrHV#~<}GBrYc`I*`#Xh|h^G5Oub>NdxaB>La837CE2WpV!z67{%x zCE+;tSxY_Pv{DH$DsK0ZZT@pVpZz`-0A=@YX#k=}U^s@b5kNm&9si`>vRde1f9zIW zn|=O~+k(z&k?Sy;#@Ef^vV5cBe%tc1kb0C&4ZD9NB>Znf@qb%)l6DuQ0K~O_O9dE(Cr!SEH9hh;C#KhdcH%h0ZF%I| zqJuaK`Ovi3R;6+HU^?fCW83V`^5a9h^bc~`e@oLJ`2VIckN}b zJpyJMPqkgn6-HscgeWARFputWIPC20tl3SQ`^{D}PyD;aVB^m>WcvFV&=2Dc>JIVG z)`#dG-Y~+?xV{1oF(Y0=l|F?K0$k7kEgdKflScSfFkhe3e>T>;439pkii7puO%u33 z9_MITJ3+@EyP z`v&z3riS=Jb1Y1=2}&zOyE1DDP>6Fa>P8IpccRBz-_fLw6-;ZSYaughddjh;G$l7~ zY~)X7BQ=%dT85GnX4P0>uiuzSVmNSAvWU>*Cgxbk<)`zO$G7C6;DlIM+R%U`(Q}9u zf*?D%KvOeT4ZS}{x54%BunsI)mkrN$FM*Yj;n(%pC)I9O9)S6NF;C41*M-)HHb1Ma zTwXe{R%@N7H38O($&AEYod)_BJ3{RH{c$OUiskp8*rO4=oz3!#=54~hrw#mL22gG> z`_m<%U&70ensC#uyA?Ho&W9BC)3_EthW9Qci?`O2q?!bYLb@+a(PnBMsg-->DHQ~& zEL=vJEMlXV?O3eOXA_Lb@(Uh#vFLM-7)16!otF`iAjpS?M$3ZqP&Ij)#c?A)=|P} za&9${>pAyuzkWb)kyhQ9Itk!M>)hFz-e#R;(h8DlK!1{hN{W(;o>%U*Hv4g46LZl; zKzVg}{D%l~Mju^@Ds8n^@RMvwmI`c{z}j$vds7&dWC?RV;>N5JcKX3p=6RP)cL#cj zVG$oTdVyMJ-X#AI#w9270{^WOxt0F4ys2$2D)kWDNEtF&=zGF^)DZ2;FBrjiA2$(o zfJhL9H^g;tz+`riwL zKVdvLG-*~7Cv_x28yJFOv*We$k?w_?7Ngu+;b}ST}#3ZY!-lQ(wP}5C$ ztf;xigr7T2tCipBD3sGF#OhRN#2~NUKj+&9h6Dl(`gFMcT4qSf$IZC_dM!|-8K?mL zNGB%7t}uV{#I^Oi0Klq-neO_!g|}kfZ6AP-vNJu*?-!o0I*)`7iB2!0qBg6#yE}W6 zufR}jlVB&rjwIJFA2~p@slQngVhqpH`+_CP7DPn2>PlAR=t$NV-ECTrr%~>rc+zN{ znKYXHIHco$oLS9L;)aIdA}2+D#A+HRhR1DJa=7(1GF+#B;}rmj!9bUcTbDhQpMZml zSA?!xb_Sk0hBrk#nx<64w%Uj@B_$gIA`=P@ub3SjDSHS%e+9S>gijeu5`zkzuwqhB zYq1Wb2NIG;YU9M_POH;WxJb1Vte#Jnntcnrz+I(YGF}09@h}o+Q+Hg>;?1-e^{(`4 zAk)s(FRy^Y?{am}d$PgPWF-w1?Sr?+baM=96ZeSD`=OUQG?qu&5gVtK6JS$rKKWi& z?^Oce%RjvD^Xb$ns=jk2=i8>&!sAGoob|y_n^5wM)S=ejEI3obRgu&u+&ddGKrLDf zZ_&ZLp2E~!zQPd1g<}@=OM%hb+HU2T5 zd{j*&fr?u!FLq7>M0-G16g({L(X~|rw_QHi?aTaez3W8R8g-*&Z)IsJxV!+v#zT84 z)ik%HgmOWv(;;8J8sst3hq5p*Pn7R?597_*wpkC&!Qt*&7hdO2%Ik3%&n)pv`<`!& zE&Ra`Dn2__ZfdXd_M*;g1i+IIAM2aMhtwF6%cl?Ap)`)WZa(*Ev%$IoAW;dEX6BE7 zJ=roJPX>5MVv#=6dlT5p_cn5GZ_K@R%Uu5 z09#p6+SnpR)$nf|0zy;9dF7aV5t6ZaDcH&hox!HW=IB~q5RC)sQ*HvSoR$ldQ13f^TDp?&Q!{lYS zkvF>F_9?L@_A@~St>^AcLz}w~a1U2( z9P!ViyJ1e0&E(MbA zVt7vxOsk*t3=UzOY^31#B(u2(OOU z?{lD<)^CAE-w3*Wh9I*Z-4Al?%=jl)Ajkc4vHMlH3Z{H}lv=22gg`T`&tJnLv}~$f zrW#S;;E#o(zdFW{#wN;OD_ZjOSd#E;Yq3kdpiGVQpXQF?MjSb`6}mGiViwG}8R~y! zp_1UGKACl$E&|CKv6RDVS;G= zgYzB>AH}oG$SYzVz#BfXc8OMncI=^hXV)UY`~6>5pSKlC8}%`s1-@Q`E5=11q;jj0 zEaZxb)=HTu%ku_~DH^neTantG=kEmurdBU4jiT(j6eIszB?RQn?;Vl3J%?3LY#X0L z;vW0ACDUf;C}BRHJFJ6*L3=WuOMFy-?LTt|-eaiE%)9~~V(so5C?Q#%BE93vK0MO( z-|<)UCAMSww0;~+{`sx($^S_aD`Nc*AtH-h!!43729QtOHAy+V;D4MmC zyN^(fe=_~4{;xY-E;g=Na^<0A$Lg?U7INN16K6sHsJF&=1a=K?&Ow-2*!9jktEb=- z?4BpTe<*6TDx@ooDMw!%=5x<+j+LEqRnTrjfbQq`m)sL< z>7nJPr$P27Ep%{fUvWN(Ie4GMt;fuHBPrc5zSTVA5xcSF7a?CN_`W~Kv&eOm)ebQm z?@RjFn^x_?7e*1zh`51#{RwBTk9pwBe=_|ut1!nSK%-yF)H6W{>?^Q9veR~I>|W{sKm{k55EV4t%7nb_|H73;&VL7i8C;Zeu~77s9pn}~rNjv`69x8n)d z9e!fuVOqB#DpY{;FG1gTDmSeBFUDyvbfLfqev(YmBS^kshv)I5>ikO4Oxr1DQ}#WZ zR{#+|dZ3Z}A41TY<_k>&=V7x(I4ibIz+=J{S zBK>(`Ee~(;fcrq9&UC94b^1vsg3gon(KRNH={vXG1I&FM2*6%rlXJ1G{VcTfZ$uZ$IjWJJWq>?U$fEDxc^Me@5F!l%_)2QS-vgv@R3)5 z5%FzsgY>fy?cNYDLYyQAQ$x1O&~({fSIS{=WLeknx$>wyj+fq$E_TeUei&Qxx(~eq zyF=f&-=^o#=9u9wFnp_`@aiJLlM^sI8FIehl z&`RoDA6vhU=H-+OJtnQWBxXg%a!HPpxH6h2_dwU_tlYHicpgeLnkyN~^pLFt7PEgq zxB(iv)S`d*Y}U**cXs$oY-Dc&1!wG>GfOw}^{gPZOLIA|ilPI%kPK&H+Y|HDOrH#I zTsn_6PDPg}9bKP5FIyqePYtqOmctOqv5Uj@vR+sD)PkhXA<25U_QZBzqV#DErAfgz z7C9Re-(+d);_^vj@cRnUQlNJ6luiz$K8he%?~jNYj@mAM8rm#a_|o@9fn?M0(P)WC zGNy|V6>v#|w2tZl;2`jRNoI zT|Ccjne{N|8%$16Qr<5w>|EaVgUbW{3*oObqI>i!t~LP(UhVwXTu%ABu&r>W$!(4y zm_Xcg^}=Gi44NaVb`)D`T;B1M_!1kET;fALn8)=#R%iH(JCq%`}Nn3{M#%t~q!-TtIKD}l8(u+J~d~?a2)q?P{J0wzA^x8_D#kwOam6@1_->yugA+?1@g?Z|dA3pH4&l21**kwkR$Pz^pN8x%OA%by+vp9u ztl8V+0n@W|^D*CG!394}FUo;TXz6zLJbBylzY>?{nR+~`w8Cn44c;cgnVM6x>(wmD z-=6H?_V1n8hBf+ja|Iz}wrtyttASCShlY1jz&+-+MM5!baeO%rQCUY#&}4WrYt&fcMIYjVjgBri0NXo@!Y3M*T$ow0vZc~JvBu%g^zj{M5apg455A>TmH z16k}zgp5H&CXX=&1!DQ5b&es?&dGO_Vlo7@VGS04_IwGbO%HU57AnwVI>P|qk}}R& z(d>>xFB-V5K)#O+^Wy4nhDn=wNCyu|l>&Xve9@bqc&+e3tF+XVN zOMWrw%*jiSPiD;x{HgRx(Vn9QUT+!M%=VBCnY1^pbi0x|w0ZA$u;hF5U=kmg^*}s3 z>8~*Bza3Qj_~w)blegh)Eslt(=u39e4?T0gf98gN^dn$SdfmyTf|eV0#2p$~mhxlw zNL$?%Bl#Q|O1h~9?g>@F`JIDWmti9YQ;c&vo{F-4bTwn51M(z_BekaqTYw>v^o0Kz zcqjx%7B-1LyGmPc+gGdFD6QhOJ<@ZgKxSf-iOmpn}7%3)~M>@4n3oS`j z?J?RP{N5TM$LjNe=N5l}06d`^!BM8`b8^L*vu84t-0#K-^w41AB==zb)y~+wDk}mG zqO$R_yqAW|dZYa($7907Vub_a-FK?1Xe(^bfOt$~jv4#WnFkZ@}_itR)(D>1R2bD+W7MJB*0lMt92R06aoGV(+;(M!QD>vEG@tCffM_#spU-VJr&8;Dv}hvicN%uZ81(@F8ymkRDUuzUWuf7X zkBIE(nu-f*8K9TYuzO|4ky=1!jQc4>hp2lcdi6c@{Ay6^ora`C;Rh+p*;5R$OXs}r zY+~_cv1Ly+AVT!LL0zSZl&IBgKc0jgUYO+Pr4Qi$9!gJD%5n)ZZ|GB;D=aoFJyxH? zY`}d!-AzqhF?1{XmY9E>ua&H&dwA`!sl?@opJ^f)=2%z5>`Q1=qIVatxSXu9;12Hb z#Z14s!0X*GBaYvHcAEQt4!OfSlj%~){cIx5Xp=CuW}sg9OCum+&WMBjRNA+|z+K3x z@TckM73KgJn;46F47#Z+ItJE|SxfdFna6?+a>qaVt*`O`6w=AijiqB<>2$Wa&1Fed zGd0Poi(pQl?iR+_j~|-D`!X8i(mttAF}c)E*jw{lZnJFPnvmM&h6>3rhggs7DFlv` z=rM%_LZ|5GisD2)K^eGC8Bk9x9aGL=UXBb=C`uYS>B-OYS*i7Pj#CePsR~v;HIQ4Q zc9cPX1i?nKVdD*8k+#1B8==OxS%~LFz1LxDC!nT~&_+J9@#OIZSWRB$I45)>-p=Rt zuS5QSlmxpawBLCdp)$p`m1K5qz2ePX5|G?oFSxp$-8j9w?2<=+!%9T(wP~1eg41#6&2A=27Y}=`Ih=)>)74m-9gm%BY9 zGiB%iPF8-6Y4!VG!WPfx?2GQN(s6MwLCw%WvT@KH=BgW4g>vhGF+4FwEY97;YT_iQj65?EXq+QLd&nmtrw}vE zl@t&bDiQ;N!2uyc1*dhf-SIz2Q1e)%vEPpt~>;Q%XadNcrjJH z9s2&S>wLk|nOFPJMdtgsu~?e=TlzmOsZr@MM|Bp=i_{Y_WkD!N$RhzrjE_}mi6yZKUlFy2NFcsyaw2&|FXP3bV4~+tmo_w%gYkO@VQFmjQh8i69Q*?R^P#$&Q3@f1l73sRXp z?t1{NjIVFa@BVJnS4<9IFghS@tf61yVaCj`3bKCK#GUzr0CoxAAm0fACAf$Io zD{6TfF#R{YWzi$)W1V*vf(n6grfXC@7=9`%8JWi0&^~$K?Zee7TAi_%D%;cE+lP`Q z?dCi%`DB4Dg>H7Go%mBDNx!Bl008-Ul5CVDZ&CD`>*8{676Ic|BL$;oi3Bw$AXR6D zbeLp8QCUpVk{Xhp7;7e@E6qi81jq<+LU5UM5e`}45j<{WWqlhq%RHtr&~Rl&`!w-k zgSm1)`Lb#wjFOGg{>qjtacDs6h}~)L8UaCC#nn|sS-Jil5lJwc#c~vDriz1IJCjU* zLOQP=rK5BY`sWn*B{et(OFH?pQIf8yvdB;p8kzNq)EpXZd4r0nk4AY{$;qJ&<=wqa z!3k*5(RnsQGDVB=89+PfiLLUyT+`?Xs>Gkd7GWVu$PPffbV)j2l{Y9NW*SE_qR$|Udb6IlVGzlW_?`%*5V5n5 z9Q9B#30A=~)}1sv{^?s|0#d2P4Y&u4n<7hGKp_bTDR;0Gd^x=$@E5aQjvr5I6>sy< zzFjWaFG}$L9>Ia%i%~KWUzr}4UMYskqC3cz_)t<)u*NP>b~Jv;fg|4+D^7Xu&XXj!o+QKP@?P>CC*Zk{aE>-(qR}X}^jSjh2yJ z2F{_Eo+LUgF9U0yeX~`uru$Nazo`M96r&rPnO-}N=D(Uhx4VQznsSi7%Uai_p%*vHDvebW2Yp-x?|k+6(Y;eys$(LqFzn9%t(gv#x8gW03%j=PyoMNO9FQ zN6DlyB@V#qI$?c@;)f@Z;-_M=%jP$a4ML4iVvH3LtrHQg0+;Km8F z%3=+Tnv?`7QI+_ob_E)?jcGjY!UDx6RuPW)vSs}o!zK1~QW_=e_;#uTCqQS2v;AlY z9F*gsmYLJ>&Qzlt`R8vUgN0Kty#z{91vSNa)jQp36XUhO;$A@!stmaJF_Rc3)Wy2? z1&jC!HfmV1q&YmRfcM?m^Kww9`c;Z*`vSic@x6sSRnt**#@Z8RQaOrl38DuHx%y zk@~8>0trfU!w?Gt<8;anJj52C04=v@M07pGARWH0^40+;ScV|sicAC5)om!9;;afD zQaJkAiG*C#9g#z8`rN=G%`Y5peHp5T@@idox~Ju6Lm!NX)1fHo%+SfJ^z zVNc4HLaeTt*h)i(BuAsQbY#Kz6)1BMUd}Ny^f}&$Op2qmqS$h>l`di!eFs8$wk6M; zB#HWahpJzRQaG0`82qjYx^j4&Jms`~);-=<5Gk(IZr1R^x7-)S7cM_rpt$8Ae5ePz z!@~)d)R-aB5Mq@x9lWuz z>)cN){6##VObY&(Pb{Y%OYqAA0%B-3^hknj`62;rf{+ra$?d?7zsZT;bZ`k={%Xrz zn6wWzut(+H)aj~MZvkHfV3YdGftzjn<}`trp96-Vb8DmSg+)}Z07qz6i_UVTdtLuz z7Otqg4*kh|o2JqJ1R`+}eUj_Z8XeQMITVWWd#P5JGtA^)Ea3lh8PI=yD?#&j`MSQJ z>`zPJy2Sf@Dy@y$l{c8lyL$|ejj3MvMF=ax^3QbTuYfjKr~NA2^Ewv-7&Igd7~6ey z_ad{@;6PvefM_P<;p1|8<|8B!o$x5va){)zLw0RRseK(Jg^YFHFW(3qt%h}_hy!PGQ-*SFYjI$-L> z;p?%fuK=v<0SeaziYc+n6fs>6v4e<+=nyg87kYU_#RsF3c=}9e#y^l9I_7T$^&^=gdys6rtda1Um>S;FVL+>Z_HV#EMmoFXTkQ zk0DFpyfWjhMMzf_cdBD(`P2b$(7+p;=s0+}2lg7faSJ^bKCVMy#H^gaoo1f-;r_?i zXssyeA?;7%r+S1p_R!;3Ud%+KtUM6Af|>Tu`5R_Bw`jvi>l?ByCZ^I~nr+yLUd%&6gJhAS#nw|DGh+j7`w31)(YP;@>DW(q~2MBX^p+oX{* zCI;E5&Jp#{Z2pTXYNrVJ#VvbM1z(8MgX?F#=hOuKPdq}W@X<~ zlVjt^<;|{0dHT?&y=}KJllsPGz1UFKd;7z6j1*%M>{#jH2NWvQe+NJsNgaq(Lkzm7 z%p_}*v2a1NV{@kSwEk84_EEa*dFO*K3k!FQ1A;J%1qHrp3}h{{1b+PNZg_~8 zXbMH0_^qGs8R|5DO~7Nx;{?>d0wJaE#4s=V*E2y*rcFw}&9JC6>Z0nz3#N%Uqed~U z7k?=K008hbOJy@q(Q9`{QFE8Z>xR>COh$pDQdu$dPUa(^-nhf+)mOa=$WG6fek}8_}WBA3sdp58D^44WAFmSfl)^1tG!nMseMDOO-p}? z_Yb_MKP2A~`jm}x?>4MD-!@m!%mRChe|`6Q5@6+5JNpz2S$Oz-b^(}q)@y$u#Lg_e z``!b!N^5s324!YRk9*r3nfH)I{Wb>#01(;R4t{Fs^)jOO$AzF_%SPawWzMwJBJIQXp$RXISHKsqS>SA5#LG}8zE7dDmv&$J!ZJ|l2LRw=ap^pb zMgF#{7}Ccq`|ao4uF(Xqi~q{5U$(#R@cnC-KKmQyU)!bs*REV9LQW<&mcQ@Hbx&W_ z^l(R?kExtrop!P`^+d#jH}st03U{$0t@@EA*q;SAAz^A9&Waro4ImOl?W?M$>#vT0 zGV+e$;0um`=?Gp00|WDFH^qxxhp2r)O~1hqMqRE}Go63WCs1BK4?+c7UOXGlTrO%o zYFDe&ojp^TEqw{h{(OVN*vVM64tE#$t8vBWkrD8O@3+u3j~Ft(#K%JD1N)e9c&In~ z_@fge6Ug|sFZQldv$a}^>+a9?^KkmH=<4D|{OWBRu=oq->cYk4{WmUv8dJk` zt5;Bkm3`S+zbjywUvv3AqTo*2Rn;?Q1C5vP{0&2p5rlq0u#JOG5&LDEg9k%{0-xT* zPj(K7B1!>Ge!Me+;OkGH?(q7neBK`hJNm8jd!|HhTcjCqB2>;EAc!e_Sv173b`1hC zQE{3CTA3cwHbTGtWLN`AR4F?FGLJ4&94{!c%aEJM<_)mvZy}CA4s2xx;_wb!6$o{T*N!^v_ix5q@9ldJx@4(CHMr9%ph7;+F zD@)6Zb&o4c$|&`=X|$TwhaRpZE0ehk^Qs8>8QAw~%0|MSsYbVCU7=OOI6KWJj_TS1 zjj+HtbEKC_joF0JpNNVjVO92agH;As6Ph_yV!!KP3g?6~&?}WxsJ7-s(>8=Tl6MGA zw=A0wIJ)X|9fUdjD&PoFX+y2ZllqwB-KK~tE}>-vI4Dn0l#l0EJRqYUH7SXJuy*I+ z5S|USq){Dwv1-j#IVmE+V#21*3k@b>hZ2JqBaQetm?ZH`vRxA(LY6#SvKzseC6zUt zldqC3+nmiLuX1qd{-v3dwML^vIVejAgX#*SMiqnVR({qXj3f5S@H$d~#<|WcjVpg_ zBGhjr(B3w_JXFjsF2LHOL78fN?Yhypj)!>fV}gn!TY~01OTFxB09i=cV3nldwUdBT zUQ{3bDNL`|J^az0fJ91hw1mPWHY*!`#map7FFZoF9Ygd7rbrMmC18-am< z&=21@+Iq@==?VNc;;BrMia_l1U|ZvwWOp-Npla{*Wa87m~>XSdCn zkJbB2djW>fs*1Zku-7#sCFWVRQm&1yTui4eJ$}O^k6)U)1*wo>6dQ&8O*0*f$551g z^2y}qX=hm*-cl30r8ar(T zM_Jq2!r|6zdVFstt4bo07WMM5C&lXr3liaBnb8froswNbw)iS(*%c_eEGXNHg>&qI${Dz=Ibo(He(g*w2K1ThqB?9RbSH8#AvO#u`Z z%V`&->+aJJt~M>YmnnyQn^EvZK8|dFvZxXywncbBN%;upkd_xv1Z@|KpqQu4Cb?7h zJ^VJQ_m{^~rRaOI5Qsvgtu^)mf6pH(K%~Gtj;&-G%je)zW#l-?nP0Z_)NT+*(BN~h zwB`nh<9P<>@TNChk+Y}+ce`HiaH!}o+P*Ya{WwM8ak}8^noH+j7`4XzF5|R*v}AkA ztJ#bvz-d~hhP!@~??=*^H+_KjOT_GpE;7d_`6@%A5;vig#xh#1D#3$zZIwE4%CYz< z_d-I0q&aT0NHuf_SGnucBws8RmR7!(avT1o-!ghc>?YHjWi!mC-OCF(;trlaK79Fc#PIU))IW0Zsnzpn z2?ObQxSK&eMckG1BiAHqWIT0d`@FrSwV3O&Npbp3kJPItb0Ct0ptt(R>x0k82>k#- zo*_zPY6x>K37DXmpwHl;UrWVHkJkf5`Q%Ds%<46DVzbahkgOnTIeQ6Mv~DoJ!Qsv- z-S%X+`_bhbshkYP#-gg&$F(_4(02|QV~kQ&dm=j)lEgHhtYjtbbkVtXydGp+$NHx=w^xwc*s{A?_N^BF66H@Xt9K5oSN6TB1+1L~FPv9e^R$c3 zW*%A|`W9Ad8WKmEzsRyV7I@W3D1>7eM1u^{tS9`$80HM?eG05@516PIx z{H1F!mIT>2-7O|3p5oG2U_n7(J{}&P@-*LdQElo^L9Ux3R0K?!8|Lp16HI4=sdreRqE)1SP(MMdZBJ;dTq+6yK$L|@14CpZSJol5atL2vV3_Dy_ z{kpRpl_4dE5AQx6-~?5>VQJWGe`;^CoT-TPZ6S0-LwgdIlaFWf8WP+H4HaI$?n8Q3 zCt4qN6or8%4^d8B#Rokb#A${45nYX16T7C~tn#KzD<(aX@RLHT=ff7{in!3D^zGIA zZ{L6H$=Y+&!FPj|8pNS$6i#a5v3v?(s?{id-(Dchb?xw1AEygnG_8zMUdX^@mILw^^(TM z({eCsxv;HZl)X^FxPht0H$3(b_Foo*MB2)ZMakNf%muM=NyI(QpR&9qtj!wMwwIQk zm(_GRoqtBGBF2We1f*C;sgK2hd@JLsxkp*VcoLr z2tCMl?bSJ$5-anvUS{kp!LW+WbJ7+!APwiPbs*ZQ|LwFuSHZ{d36AIP>qb98NcyK= z+4ga9?pzjKECGGy@rOLZD`WA9W~lIGVxvDb*#4!SobM zuOD{`SDo{vFk#EG;`E14bCT5;bRH#aAI_fm)YRC5>HLMo5qQY-0u5HdutA$H>`7zC zFVi7{J9U;-?vv6^q*@l<9?6KkAv zrLOm6SM2-cTuqO?Tz>|~-i%bgU-LQm#moD1+2wBB7(wrOJu-2JE+{H;@7E_#jhNXA z$I6XQs1_NQ|NF7GKLEQMtW*7={`&j(Mm`iIRz!E?n_iJ z#h7~0I8Fatd%Z5t?smEcy$`&YHrS}e(OY>A`|5S)L^otXi_5RN_P;ti3#cf%upx| z=j_hh=id9=J9D2qd-ncjp2w16y`{wu^Q@{8BRyd--!eAZ;2nJ&wsHCJk_Y%u`usb& zIB@?H6WI9cdk;#U@pC$M$>T#L{RYh3Q@eY*d(txaQ}w7Y7^<}(UPkaVrvPEyv~c@C z81&AJ_zR9JUEkYOxWeLHW2oB{stG)v6sN{d#D8U98TjUZ^i(xzt;1o23AMLX4_k>|`qh(WeY0^LEVA zCMPS)4dfDflYAMH98|PvU@yH*omLQ7uaQvpDEFuY%Q07p*+_$rviN-bkmQmsudtk6 zlj(Y+LtCt(sjuH7-C9V`ZqaSHRw!XKS!~$8u--?QQL*jIqczdHEyw1*z5c^s)>|*m zKF8?dW2VKgDF^WQRv?&6zl`;kF_n($_V8vtTij_o*Y-RtbLs)#%3MxJtzzB9H(G`F zQLos;x*Alhu9w=YwfMA}@_D7Ms1d*Wb`R!$b96guJCmD>OQeKUgnaE{5!@oF`Ptxi zVbnT)iKr#yyMA%8Xg=0U>GsE)FIKdmiQ=)VI_ySY5pPcC zBUMoo*Un%KiY_yCTc4V_u0@m4Ik7oZBEBiF%+Mr*>_qEUiYgbF5+4AYe(5 zQa9mycnawvK1abiyFsVIhlxC9AmXB0NzLBS^G1qCT%RuM8L+4xEbDDb)oay^A=fx?-#X6V9lf-x?2@5hEr3{5 zwDNlGYcaj@{ z5yHcL_<&hZLzb3tZr3#O>$lO2(ov@UL;t;R<`jjE)G_e{r~1`1D>l43_oJriR{O7Z zyk~YW+W#uy^xaTbY?hXgm9o|`!+vd_>f`+x(9`3Y+1aR8%6Eajv#dWgy$~fLJ@qL4Gx3+!O|EL+&fH_$n@lEeK?z>?>W+Q*dnnrheWz1vR5M=y zIgB_#lg8uX1gZp$Z@s>9M!{GZyxO1Vh)c;CP*@_ zU|tVeCsLV7sW$vPk#a@3aY?I}t}(PR+Fz$utybPg?Wlaic~W5*MzKGXIhhaEy?#ym zSu@9Xf%WX{iq5y(M~Zo6plXj?rxfx2mr);itzYx1xOBql^7!}Nj#^Q@n1%+picJ;~ zOZZ1Y#~E&#>_|u)M5A$UF-Ffx5O3uWW%sbV>jld0lE@f!-lZZhfAPwW89X|W&paYf zPsuy&UQ?^fvDbArKJQ^afo5hBPV@=r{x~+tk~{0t8As3 zT=L;m;c6l-L8_!uCQdqy6IXHTpSvKSKUPs-k#C`qqp?m(7SiTueD*FdLu*oUF3#+Z zxT*Lpz_DjryPsd-h)i2}L*Qvc;DDOy^xHb@NsODBi{<1qUDbnB*20leGBREUQrQtV z8T_`pn^*A5ef|2!Rm#hr&BO*S#srFAy+N}?T_EYouESi@^a+0BVOv(9nnjKPqD*Fe zEoJD&>k^H1GP|ontaG=`wfbk&%+D#W=y5${yC8Ypx70{%0RCx=>V+W1lJZM|-q?+- ztW&Rp14g86CrSIGR#Xb@##-;0EJl*?h%G&)IYVo0AfRp|YpQZrq!SjpR;n{fw;B~1 zaVTl(+b-+eCXb2OB7V`WU9)wFuf13r=|sLXI;yG3XIJuGx{sSlQ}fvsZxiY%Nl%9d zgsu-lJqRbR=d=tEoRm@GYnIrrQ_srRMLau4yxAA25%MIcJ|d=;;$Y-C6Xne(EKOrO z^y-U0ngu&szpQp_x^)gdK3RjbNabh7P6uNOO+?-k&elnz7_@7IHqilTHJ)b}BG&l% zW0v^ac3Ju~$JgMAg|7(a89t!BR_nU-;#{2bdJm9cBCBz8$eeK{w+*eYxInMo}XVTG4+Xj;U&z6GTnPPCDdBJ z=XCeuI-P`Q_z-J6l|+N?+8la_4LmuakxU_JHB4@z=8~pYk)&H-q1{;4YclR9&ef zf*;qcm3IUUE}2rU@z{d}RfcS83JE2en1O$a3P=;W6S5sRnjJUmpEfxeJ z28+93a9%v25G0Bi@ZR|=#Ro&fh{2Mkj=y>S1ZoNpgEd^ScG@5mPzl!p;PDp=1K~)6 zIxzqaes?a4{_`Y$cMyz({q79(e{c_M7~5+f1R)LhCM+E_ne`yJQAPU<5R589&h=GIfOQ{LK zb_NY7dKV6Ey)jz8^zgkaCeiCORVbCVHhi+2x%B(Y0l4bYL~80MzpIr7qd%+;AK>+{ zo(K0!lcX1J4=MHco)g7>EgWI~(f!tg+aK@S+C_;${a4{E21$7`L3TZ4b-aYmF$vg> zK&!L#kZ_HX^i$g+l7w3bLd_>a+HGBI&YetbvOSlamD1FGTbNk$dI%O|qrfo~b*gSr zzN428q?k19n>XWq?y1Cpd#)NgGcW4m*JXk#{28u0oVKNkjXX^~qfb6z+lg7vlr!Jc z*^hMI&a3?-#(D27er`-mTD9gN^U0XlyEC>iG1hB)6wy)CN3yim10zJX)O{cN2?_n) zj8tagM;%5ne4fQx`05(Emr< zvvPKEm9#W<#+j6o>2Jqyz=(djk##XZLLeX*KN`f30zL>72nIuf_|g0z1QPi0qX0So z&pa4h0LVxD%7?*z%HSw8F$|3c0naP^sw2P;LZN^>ekh0^h6cf)zvTSrUwZ)<9PnEU z2kIg~0uUq!&`B%+gMtiy8SbA`3h-TvvtF>KgO+_pELvcQ^ z|5uiVLZbfS;np*4QP0PdaX3ND@kV< z9$o59TNy$OX!3!R!`*3SFPY^GpN*R3)4rPJjF|b>R5O!+J0{Je!`J8;_V+5&&wZyk z2lX(#MoVMirxUqz)ajGslb?6?9lmzP7%)cm3_V=or1)bi`cU}XVeUD4S|3b|CFbK< z{5f+zse^DM^E#y4Bbo`u^7M&`YmKIe`mchv{%4;tv)U7)?d9DA9P{djJx z-9+tP7^VD|%Q?Qs;XP&^a-#9;r{OtZ?v>OS_PVmGi66M7#03qwh^fpC6$w}T+{|>J zh$gO3!+ICHBVBE)Cs7hr;rcxLxlOzEm{aoCF^}_BY}&_@8mbB3?OMsbxX#f_`{-TQ zF;EN_|p49T=%Ij)%fA*Wj_CyD3Y4#q~)%oJ@FRv}!%1_WzSk;$jE4+G`zfvYk z2llqI{dSQeojK%TK3!xHg}m*>j;Qj}@^Zu2mumW;5qXlT)2Tq7XnAR~bmN;j`lZvO#6c=1k0~SRt3k};R&X5H7|3MDk>3t_2M4J*yV|2 zzsyLUWoA9BddY|2bn+s*GZ-EEEle&uoz8Gny(6?P-f3`!rlW^5>pfK>_R{Nu>*HK< z1-=)FWP4cxoFpGT-gIW0H``jnaH%|TfRSji7G!xJKW~&gsBIVxB))i2P&bJ*nE!g0 z&ZA)PbI%?zqt#~07;;x#%1=BUHZ^etamdwluG@B<-^yvzjv%&MUOWqy$pY-VF$@o zR!+^&Lw<36G}%>H9olR!o=hie$(`S>f)Xfd_Q61q2?RN3+mMIclpkD z?hsmf1zki0`{|^lIp2E5sNeRP=X-VTBAEzsV|%dob8XU1O2+3HGXu+)ypadywJtpA z-K5GnR?5mwlrO4MoMP7P>3_sb+O0|SZ+SL-Goljgy8NOln^QO=!Y|9>k}$&jmSj!5 zJmYygHRa+@1Mj!`Ed0)8JA=943+|&A@sjhDHwj&pA@VGlX*Y~BItfVk9J^SI6;dQK zkX?)kUR(U+S7Dh(iyseNMK8qlp*o1L=~8`GMar%hGhk0#=a@R~6vKQTJdRrP?aOJq zp|BrIvti$ea65WCpn>0Hx<$oRkVX42BAYfnvLoC$^uz5jnhoYP!jHZ9NLK)%g@twx zD9^zVQg%;v%!*_bsBCUDrfe0)`SLH?K%~MVXTIOrIk65KAgmT#c*nKTE0(;Ka1`GHEMY`xU9VBk??x4vaqeZZZ!0vu{54Lz@eW@$~=@$2~RFo#lI@$7c=Y%4Di@oGraS4QupI?(eURty_Kj zb~X3DSf8n?Zgs+4fvYVEY9y@^dL_b@jkjbA4aez5tnId! zHR&R$1Iq?2Q^owfFrK2uorqwPNTjOdrzK5CMbqW)oyMFMN`W5u?-x4mYK0`}^H=30 zU%Dz$YKvIz6Sw5KxeXSHap0o4DuJv6x#KFqGDKTFLxu#aFv6~8(H=|<6s!|3d-5sPubRbTtoIVdX7-}K2 z$aq!K7@;Igwt)Qdi>XC@iX#2g>Ra?DHyKX!%OuiO5eDd~SR!vfeTGb{#dTx_xvR3N zFJpO5GTHc2S)lSE9^NVEC(7-s;he8q`5d*4q(2ACMGGI+vr$Z*5!FPah%)y@YQUSz zZInpN#E2bZ-iWGle#Yq-_)2D5UKK?AbphiKb?P}2Jg%W5;#WISuMvsEsh?_Gn5>%1 znxP%d--}xDtSkBHw6~w!xrWc!6BR`^>RafT=!DI^iKis&+1;yMXfTCM(5_7By<_wF z;Gic%ignW_7J6W0_C8n8TW1*)Q~9A@vi3ul^t~a8@UTQWdFi>i#&4eA!|GaSX&1^$ zr^}D_{D#yYZ}MAOF%Zsd6K&hty1OS%C1HD+MG9qI|SVR1es{NDeJb& zOW-}&CLDZ=-c5TdqczDB9;xJzOPkfEOFi7f|HysH`^yW1zOY3?DN{NVKX`2ez z&5AxkZ7ms4k^1B8l6v7XVk!Q~m58$B&+Kw#d7mG?y4E)B`E`D(S<;7-qKL5mlykdp zXq;K-T|fMiv9SE|dRm704>qKI3gzw$B5>Til{e4h6^){{-=~&}ag(IVlitVqiSXxj zRB=S*67r$d$x!B3M_m59YZHA;K5tx~ZMPd(I*is7=JzU#3~ zt#hl_LD=<#`A0E>L!G;6nfD#bV0~?fNY}9*bz4&7`(+pd3|{$I+o8o#Rp8L|UeKT= zxfzXmcJ~l`#I(q#g85jlT>{;_knj<7<4XHM!iiOx(4@DOHYD~%@@aKPovRnj z<>!X?I@0Gkg;q>Pc1lh@w#R9x`;gqY)4;q5ea5`)m*^Tv6b(u>%%mq=^BSQ`BJ1s; zm-4)A42iJ3abb4yL6`?7aXe%Hqs5QojvM8^n-+8XTOyy$quOL2*<*>R&XQ4$PxCXI zF4VGb-kaNQQ+XBid7qfQf(#w%Fv|PMS5TNxlj(x??94X~ z*ZII!hJeeG40+cD`JF(#_t3(HO70vJ+6BWY=jX6ww6FKZX-m0O8(I{i-Ox1CF0@v; zhxX~G%wDm&5CN30m34q?P?R0fn&qV@64lNl^4>NsWm#U*kWY2>rdY*i4ay^UNyZF| zervl}gB{DOTd4Gy3O#g$7Kuy{(RR2q%Dd2F8KddoY%%`j1H3-iiR*_tmLrg&jdiN#!cLS)1$%Mb93e%{`syWgT;kBBjfDmq1l(dcXLc4_NaL0N&*Tv&W@xj9_v zVS86^I_5(uVJboi@axRedNtjAy!cjHW#Ht7v^jm8l4Z&RVr;H;OuoWr8zjBe z^V)u@1Vi@lag8nh8jWj`KEP88DlY6Gn#d3?3;}8P3h(72Rz(wH4Zj+pi^G!Uh`&pz z#e(f;fj?ZHv&Y~^WG}kHE?G@CEI0A>Y+RVIKZ**uIxF8q)gP34vM^)JMIn6LBH3T< zf3x1ndk*{BiFv%!G#Gd*h{5*&f6f{0QmG#imu}pYzmA^;wT0xbn^bN$m!<3U67}Uw zE@;10(BiMCN5uuuYA|;a!VuQh@Y<J(i{I;U-X}=1?kq6frn)ptjcC zJA@iMNOARv^1hE}*l7v$YJp|bM!T#6R?nbtWA}@z0hZYE&Rc=LwJc#f5n3l_qisa zYbA$P@(0RqY#BT^!K1D|t5Gc8c*XBJO;oS1YIk<?4qu7g{eDlV;F=T;~Nj5xDtP$n3y>hKYIF*at zB}OLFCH(UDFqgFC(2TpKvtx-*ZJHnO^`Z!D_{F731cdq$6~c@hZZc`GAa(p)4zx3T z$8T_rwezdGyMCJz@2-iZ^80A#JJuC5df)N-2friorA_9E4*%zx?y6NK{wM44kG7(s zKgKQ5-HQowHsrotsp^P&R#4C|zJ6OMx-VQ#t}(vHHaJ7l)BBpm^o0ip@76>#9uwWPj``{? z9WR5jdt$G}f??ew<93IcAKTN*{hN)mZuGpY=f8-kz2f2HuIRtX6>uz=ugUfLmU{nv zu7WzGn$B50iRvZwZ_-4HBUan9OBYdBn)W=qeUg!&_Be4S&O`}9z`p4j8K(qlEzr$QuPOp$al zhhq{WUhVty9hxpN9$;4&V+nz(Zx&*~Do6@qIuh3JLSJOYFg@39o6FA7d7LAM8&xOR zv^88Pi;9|!n)`vL+ietV-^+Gmn`27cbv1UyP*bcgm1MM)ialVsH=3Rn-Xh%W+h-J# z`E~vJ-f~(v&yu#&QBCH{Ev+{%Mb(6cTUSSiGOZJ>?BjKSTl0c{_rPRJ5W&cNi|)S2 zmgP5L7^I>v1a8CWNyDdUiLdx3K%zqJ9M9Dh$>eH@LdcfAh9!T}j7rGJZ64vA0e#^W zF|99%BuQ8J8QIP2Uc~89uBj3hP1NRj65G$%I;h7l>N|()_pg)a}(qKOuBu~=z|lNpo# zcS&kOC}9MODeMOsd3+H=I2oZ`Odw?z-^lbRx*9spur~G@3aj(Y;Xz)GBqM2W8N~*t zDEsa6^6;H_Pmh24PH0W@Ug7axt$u8S4Y#b%wu6W1Ow@pQ&^aJ#B9yyWv$(R=hLC$fM5qm*%E?P>S zo_pM>NqTtaITaQ;S5*9IBT!jR)^W!7B-# zoGoV8#+P%zhNEN8zEq=1+~kb3l-@NEVB_xJh;iFv6YSlxHrrB&U7JSOFgwL(%kjyI zP{u1(-MS{pwp)10*FoRF4Qp66RO?G_^g3V}sR@#(y}eXf`@plG?VZ=~wn`61=h9NO zc8TL#?TfDr4@eI7>OMc?;c*$yoqb_w?LI#I8PPF()$uK?e#xEMbOH^Y*f0x=DZZy# zww@aKjo--9eA*V&95AL8?I9Tu+MKqBHnOPgwXqYR#0Y)kugZj9c^X3(*$7o()Z>?Y zmhPG5ciFv(X#XOLr87S=zw_e3#(qjwOUnzQURRsA90R{fDR)ILyPXvqJ+7A?iUSQB zs{^R(9>ETiZz!ynkn)Rm*X5HK?PH(IeRt`wQ=?*`=jN@u$Ib%Ip%s;tk%w!`da@<5$B2M#P6M*)fuu@~_U(M|8_6%sRp5L+Uw-EDUO5CkMo-j4My~7WQ zC=nQMMoguj$Kjvz^dysoUd)5WWW{6>nRba*53`VyNz3B~B%u};G_}*^i zSYH#?D?7ID>oK$Us24q%)FX`ncE3XgIIJ5Es<3XKx$!hen!k#L3_bJg^`90OJF)8I{r8&l<`F8?1JIGcZKKfKJvc)&7n#3 zw2JrbA=z~k;FmgbY|t#c!J+SbQQ3bPApf5@;}28&UvSU=VsZaTd|-g7{Dt`NBLF%h z0MH$NBnS!68zdZ{KLWrpKxlAj1PTd)qv1cv5E4L9xUz6041|C~iTMR^X@Ka!0a64U ztfwoG4Fp$| z{I!$+wUaRXD?t4VaQZnyYPevGYNpOOO8cv4>R1;CH)jmi1qA)|T9-1`+{zROd~y9n z0(?pU4KoDGIy<;I0v*x-YdQm%*b%1!;{}$~_)CyRd5|lB_(Vm45RUe)KnpIQpK$9h zJoldlgX@k9G5DW-AO`=@37`*u^a3{`idN<>1|ZyNspFE84sN*X_LnB0{{-KXrU0XM zumH{)XzSNW6N7QMTO8wRLd6c8WxhLj)-0!2WfP#6>i6W~YlKww-D z2p9KXu8F5J_8u`X0U*SHmftoIk{@U6_dvg7xF&%U!)+k@-(fgu8`J2(Iq{Tob{x4-8A!VLnBEXzxQ3_!wYG(-Y|kdlIkOG=_;;F1C`ek4)` zCJp765CEReK#CIo-$ig!N6G;sX^F+yxVYJYz-YKQLP{JeErXB{mqJ5 Date: Mon, 8 Oct 2018 18:04:09 +0200 Subject: [PATCH 02/18] Add v1.0.0 --- .gitignore | 12 +- .swagger-codegen-ignore | 23 + .swagger-codegen/VERSION | 1 + .travis.yml | 14 + README.md | 162 +++ docs/ApiTokensApi.md | 225 ++++ docs/AuthToken.md | 15 + docs/Document.md | 33 + docs/DocumentAttachment.md | 17 + docs/DocumentAttachmentsApi.md | 173 +++ docs/DocumentSearch.md | 24 + docs/DocumentSignerTemplateConf.md | 16 + docs/DocumentsApi.md | 225 ++++ docs/DocumentsSearchApi.md | 64 + docs/Event.md | 18 + docs/EventsApi.md | 144 +++ docs/FileFromSf.md | 11 + docs/InlineDocumentSignerIntegrationData.md | 11 + docs/InlineIntegrationData.md | 11 + docs/InlinePrefillTags.md | 13 + docs/InlineResponse200.md | 13 + docs/InlineResponse2001.md | 13 + docs/InlineResponse2002.md | 13 + docs/InlineResponse2003.md | 13 + docs/InlineResponse2004.md | 13 + docs/InlineResponse2005.md | 13 + docs/InlineResponse2006.md | 13 + docs/InlineResponse2007.md | 13 + docs/InlineResponse2008.md | 13 + docs/InlineResponse2009.md | 13 + docs/InlineSignRequest.md | 27 + docs/InlineTeam.md | 12 + docs/InlineTeamMember.md | 15 + docs/InviteMember.md | 12 + docs/Placeholder.md | 17 + docs/RequiredAttachment.md | 11 + docs/SignRequest.md | 31 + docs/SignRequestQuickCreate.md | 44 + docs/Signer.md | 42 + docs/SignerAttachment.md | 13 + docs/SignerInputs.md | 16 + docs/SigningLog.md | 11 + docs/SignrequestQuickCreateApi.md | 62 + docs/SignrequestsApi.md | 284 +++++ docs/Team.md | 17 + docs/TeamMember.md | 15 + docs/TeamMembersApi.md | 130 ++ docs/TeamsApi.md | 284 +++++ docs/Template.md | 15 + docs/TemplatesApi.md | 118 ++ docs/User.md | 13 + docs/WebhookSubscription.md | 16 + docs/WebhooksApi.md | 337 +++++ git_push.sh | 52 + requirements.txt | 5 + setup.py | 46 + signrequest_python_client/__init__.py | 71 ++ signrequest_python_client/api/__init__.py | 16 + .../api/api_tokens_api.py | 430 +++++++ .../api/document_attachments_api.py | 331 +++++ .../api/documents_api.py | 430 +++++++ .../api/documents_search_api.py | 133 ++ signrequest_python_client/api/events_api.py | 284 +++++ .../api/signrequest_quick_create_api.py | 133 ++ .../api/signrequests_api.py | 545 ++++++++ .../api/team_members_api.py | 256 ++++ signrequest_python_client/api/teams_api.py | 545 ++++++++ .../api/templates_api.py | 232 ++++ signrequest_python_client/api/webhooks_api.py | 644 ++++++++++ signrequest_python_client/api_client.py | 621 ++++++++++ signrequest_python_client/configuration.py | 247 ++++ signrequest_python_client/models/__init__.py | 54 + .../models/auth_token.py | 251 ++++ signrequest_python_client/models/document.py | 775 ++++++++++++ .../models/document_attachment.py | 311 +++++ .../models/document_search.py | 507 ++++++++ .../models/document_signer_template_conf.py | 278 +++++ signrequest_python_client/models/event.py | 337 +++++ .../models/file_from_sf.py | 144 +++ ...inline_document_signer_integration_data.py | 144 +++ .../models/inline_integration_data.py | 144 +++ .../models/inline_prefill_tags.py | 192 +++ .../models/inline_response_200.py | 194 +++ .../models/inline_response_200_1.py | 194 +++ .../models/inline_response_200_2.py | 194 +++ .../models/inline_response_200_3.py | 194 +++ .../models/inline_response_200_4.py | 194 +++ .../models/inline_response_200_5.py | 194 +++ .../models/inline_response_200_6.py | 194 +++ .../models/inline_response_200_7.py | 194 +++ .../models/inline_response_200_8.py | 194 +++ .../models/inline_response_200_9.py | 194 +++ .../models/inline_sign_request.py | 607 +++++++++ .../models/inline_team.py | 170 +++ .../models/inline_team_member.py | 246 ++++ .../models/invite_member.py | 167 +++ .../models/placeholder.py | 306 +++++ .../models/required_attachment.py | 145 +++ .../models/sign_request.py | 719 +++++++++++ .../models/sign_request_quick_create.py | 1093 +++++++++++++++++ signrequest_python_client/models/signer.py | 985 +++++++++++++++ .../models/signer_attachment.py | 198 +++ .../models/signer_inputs.py | 279 +++++ .../models/signing_log.py | 144 +++ signrequest_python_client/models/team.py | 312 +++++ .../models/team_member.py | 246 ++++ signrequest_python_client/models/template.py | 259 ++++ signrequest_python_client/models/user.py | 201 +++ .../models/webhook_subscription.py | 292 +++++ signrequest_python_client/rest.py | 323 +++++ test-requirements.txt | 5 + test/__init__.py | 0 test/test_api_tokens_api.py | 62 + test/test_auth_token.py | 40 + test/test_document.py | 40 + test/test_document_attachment.py | 40 + test/test_document_attachments_api.py | 55 + test/test_document_search.py | 40 + test/test_document_signer_template_conf.py | 40 + test/test_documents_api.py | 69 ++ test/test_documents_search_api.py | 41 + test/test_event.py | 40 + test/test_events_api.py | 48 + test/test_file_from_sf.py | 40 + ...inline_document_signer_integration_data.py | 40 + test/test_inline_integration_data.py | 40 + test/test_inline_prefill_tags.py | 40 + test/test_inline_response_200.py | 40 + test/test_inline_response_200_1.py | 40 + test/test_inline_response_200_2.py | 40 + test/test_inline_response_200_3.py | 40 + test/test_inline_response_200_4.py | 40 + test/test_inline_response_200_5.py | 40 + test/test_inline_response_200_6.py | 40 + test/test_inline_response_200_7.py | 40 + test/test_inline_response_200_8.py | 40 + test/test_inline_response_200_9.py | 40 + test/test_inline_sign_request.py | 40 + test/test_inline_team.py | 40 + test/test_inline_team_member.py | 40 + test/test_invite_member.py | 40 + test/test_placeholder.py | 40 + test/test_required_attachment.py | 40 + test/test_sign_request.py | 40 + test/test_sign_request_quick_create.py | 40 + test/test_signer.py | 40 + test/test_signer_attachment.py | 40 + test/test_signer_inputs.py | 40 + test/test_signing_log.py | 40 + test/test_signrequest_quick_create_api.py | 41 + test/test_signrequests_api.py | 69 ++ test/test_team.py | 40 + test/test_team_member.py | 40 + test/test_team_members_api.py | 48 + test/test_teams_api.py | 69 ++ test/test_template.py | 40 + test/test_templates_api.py | 48 + test/test_user.py | 40 + test/test_webhook_subscription.py | 40 + test/test_webhooks_api.py | 76 ++ tox.ini | 10 + 161 files changed, 21793 insertions(+), 2 deletions(-) create mode 100644 .swagger-codegen-ignore create mode 100644 .swagger-codegen/VERSION create mode 100644 .travis.yml create mode 100644 README.md create mode 100644 docs/ApiTokensApi.md create mode 100644 docs/AuthToken.md create mode 100644 docs/Document.md create mode 100644 docs/DocumentAttachment.md create mode 100644 docs/DocumentAttachmentsApi.md create mode 100644 docs/DocumentSearch.md create mode 100644 docs/DocumentSignerTemplateConf.md create mode 100644 docs/DocumentsApi.md create mode 100644 docs/DocumentsSearchApi.md create mode 100644 docs/Event.md create mode 100644 docs/EventsApi.md create mode 100644 docs/FileFromSf.md create mode 100644 docs/InlineDocumentSignerIntegrationData.md create mode 100644 docs/InlineIntegrationData.md create mode 100644 docs/InlinePrefillTags.md create mode 100644 docs/InlineResponse200.md create mode 100644 docs/InlineResponse2001.md create mode 100644 docs/InlineResponse2002.md create mode 100644 docs/InlineResponse2003.md create mode 100644 docs/InlineResponse2004.md create mode 100644 docs/InlineResponse2005.md create mode 100644 docs/InlineResponse2006.md create mode 100644 docs/InlineResponse2007.md create mode 100644 docs/InlineResponse2008.md create mode 100644 docs/InlineResponse2009.md create mode 100644 docs/InlineSignRequest.md create mode 100644 docs/InlineTeam.md create mode 100644 docs/InlineTeamMember.md create mode 100644 docs/InviteMember.md create mode 100644 docs/Placeholder.md create mode 100644 docs/RequiredAttachment.md create mode 100644 docs/SignRequest.md create mode 100644 docs/SignRequestQuickCreate.md create mode 100644 docs/Signer.md create mode 100644 docs/SignerAttachment.md create mode 100644 docs/SignerInputs.md create mode 100644 docs/SigningLog.md create mode 100644 docs/SignrequestQuickCreateApi.md create mode 100644 docs/SignrequestsApi.md create mode 100644 docs/Team.md create mode 100644 docs/TeamMember.md create mode 100644 docs/TeamMembersApi.md create mode 100644 docs/TeamsApi.md create mode 100644 docs/Template.md create mode 100644 docs/TemplatesApi.md create mode 100644 docs/User.md create mode 100644 docs/WebhookSubscription.md create mode 100644 docs/WebhooksApi.md create mode 100644 git_push.sh create mode 100644 requirements.txt create mode 100644 setup.py create mode 100644 signrequest_python_client/__init__.py create mode 100644 signrequest_python_client/api/__init__.py create mode 100644 signrequest_python_client/api/api_tokens_api.py create mode 100644 signrequest_python_client/api/document_attachments_api.py create mode 100644 signrequest_python_client/api/documents_api.py create mode 100644 signrequest_python_client/api/documents_search_api.py create mode 100644 signrequest_python_client/api/events_api.py create mode 100644 signrequest_python_client/api/signrequest_quick_create_api.py create mode 100644 signrequest_python_client/api/signrequests_api.py create mode 100644 signrequest_python_client/api/team_members_api.py create mode 100644 signrequest_python_client/api/teams_api.py create mode 100644 signrequest_python_client/api/templates_api.py create mode 100644 signrequest_python_client/api/webhooks_api.py create mode 100644 signrequest_python_client/api_client.py create mode 100644 signrequest_python_client/configuration.py create mode 100644 signrequest_python_client/models/__init__.py create mode 100644 signrequest_python_client/models/auth_token.py create mode 100644 signrequest_python_client/models/document.py create mode 100644 signrequest_python_client/models/document_attachment.py create mode 100644 signrequest_python_client/models/document_search.py create mode 100644 signrequest_python_client/models/document_signer_template_conf.py create mode 100644 signrequest_python_client/models/event.py create mode 100644 signrequest_python_client/models/file_from_sf.py create mode 100644 signrequest_python_client/models/inline_document_signer_integration_data.py create mode 100644 signrequest_python_client/models/inline_integration_data.py create mode 100644 signrequest_python_client/models/inline_prefill_tags.py create mode 100644 signrequest_python_client/models/inline_response_200.py create mode 100644 signrequest_python_client/models/inline_response_200_1.py create mode 100644 signrequest_python_client/models/inline_response_200_2.py create mode 100644 signrequest_python_client/models/inline_response_200_3.py create mode 100644 signrequest_python_client/models/inline_response_200_4.py create mode 100644 signrequest_python_client/models/inline_response_200_5.py create mode 100644 signrequest_python_client/models/inline_response_200_6.py create mode 100644 signrequest_python_client/models/inline_response_200_7.py create mode 100644 signrequest_python_client/models/inline_response_200_8.py create mode 100644 signrequest_python_client/models/inline_response_200_9.py create mode 100644 signrequest_python_client/models/inline_sign_request.py create mode 100644 signrequest_python_client/models/inline_team.py create mode 100644 signrequest_python_client/models/inline_team_member.py create mode 100644 signrequest_python_client/models/invite_member.py create mode 100644 signrequest_python_client/models/placeholder.py create mode 100644 signrequest_python_client/models/required_attachment.py create mode 100644 signrequest_python_client/models/sign_request.py create mode 100644 signrequest_python_client/models/sign_request_quick_create.py create mode 100644 signrequest_python_client/models/signer.py create mode 100644 signrequest_python_client/models/signer_attachment.py create mode 100644 signrequest_python_client/models/signer_inputs.py create mode 100644 signrequest_python_client/models/signing_log.py create mode 100644 signrequest_python_client/models/team.py create mode 100644 signrequest_python_client/models/team_member.py create mode 100644 signrequest_python_client/models/template.py create mode 100644 signrequest_python_client/models/user.py create mode 100644 signrequest_python_client/models/webhook_subscription.py create mode 100644 signrequest_python_client/rest.py create mode 100644 test-requirements.txt create mode 100644 test/__init__.py create mode 100644 test/test_api_tokens_api.py create mode 100644 test/test_auth_token.py create mode 100644 test/test_document.py create mode 100644 test/test_document_attachment.py create mode 100644 test/test_document_attachments_api.py create mode 100644 test/test_document_search.py create mode 100644 test/test_document_signer_template_conf.py create mode 100644 test/test_documents_api.py create mode 100644 test/test_documents_search_api.py create mode 100644 test/test_event.py create mode 100644 test/test_events_api.py create mode 100644 test/test_file_from_sf.py create mode 100644 test/test_inline_document_signer_integration_data.py create mode 100644 test/test_inline_integration_data.py create mode 100644 test/test_inline_prefill_tags.py create mode 100644 test/test_inline_response_200.py create mode 100644 test/test_inline_response_200_1.py create mode 100644 test/test_inline_response_200_2.py create mode 100644 test/test_inline_response_200_3.py create mode 100644 test/test_inline_response_200_4.py create mode 100644 test/test_inline_response_200_5.py create mode 100644 test/test_inline_response_200_6.py create mode 100644 test/test_inline_response_200_7.py create mode 100644 test/test_inline_response_200_8.py create mode 100644 test/test_inline_response_200_9.py create mode 100644 test/test_inline_sign_request.py create mode 100644 test/test_inline_team.py create mode 100644 test/test_inline_team_member.py create mode 100644 test/test_invite_member.py create mode 100644 test/test_placeholder.py create mode 100644 test/test_required_attachment.py create mode 100644 test/test_sign_request.py create mode 100644 test/test_sign_request_quick_create.py create mode 100644 test/test_signer.py create mode 100644 test/test_signer_attachment.py create mode 100644 test/test_signer_inputs.py create mode 100644 test/test_signing_log.py create mode 100644 test/test_signrequest_quick_create_api.py create mode 100644 test/test_signrequests_api.py create mode 100644 test/test_team.py create mode 100644 test/test_team_member.py create mode 100644 test/test_team_members_api.py create mode 100644 test/test_teams_api.py create mode 100644 test/test_template.py create mode 100644 test/test_templates_api.py create mode 100644 test/test_user.py create mode 100644 test/test_webhook_subscription.py create mode 100644 test/test_webhooks_api.py create mode 100644 tox.ini diff --git a/.gitignore b/.gitignore index 6c475db..a655050 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] +*$py.class # C extensions *.so @@ -13,9 +14,8 @@ develop-eggs/ dist/ downloads/ eggs/ +.eggs/ lib/ -bin/ -include/ lib64/ parts/ sdist/ @@ -38,9 +38,14 @@ pip-delete-this-directory.txt htmlcov/ .tox/ .coverage +.coverage.* .cache nosetests.xml coverage.xml +*,cover +.hypothesis/ +venv/ +.python-version # Translations *.mo @@ -54,3 +59,6 @@ docs/_build/ # PyBuilder target/ + +#Ipython Notebook +.ipynb_checkpoints diff --git a/.swagger-codegen-ignore b/.swagger-codegen-ignore new file mode 100644 index 0000000..c5fa491 --- /dev/null +++ b/.swagger-codegen-ignore @@ -0,0 +1,23 @@ +# Swagger Codegen Ignore +# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell Swagger Codgen to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/.swagger-codegen/VERSION b/.swagger-codegen/VERSION new file mode 100644 index 0000000..a625450 --- /dev/null +++ b/.swagger-codegen/VERSION @@ -0,0 +1 @@ +2.3.1 \ No newline at end of file diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..86211e2 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,14 @@ +# ref: https://docs.travis-ci.com/user/languages/python +language: python +python: + - "2.7" + - "3.2" + - "3.3" + - "3.4" + - "3.5" + #- "3.5-dev" # 3.5 development branch + #- "nightly" # points to the latest development branch e.g. 3.6-dev +# command to install dependencies +install: "pip install -r requirements.txt" +# command to run tests +script: nosetests diff --git a/README.md b/README.md new file mode 100644 index 0000000..ab5e8d5 --- /dev/null +++ b/README.md @@ -0,0 +1,162 @@ +# SignRequest API Client +API for SignRequest.com + +## Requirements. + +Python 2.7 and 3.4+ + +## Installation & Usage +### pip install + +If the python package is hosted on Github, you can install directly from Github + +```sh +pip install signrequest_python_client +``` +(you may need to run `pip` with root permission: `sudo pip install signrequest_python_client`) + +Then import the package: +```python +import signrequest_python_client +``` + +### Setuptools + +Install via [Setuptools](http://pypi.python.org/pypi/setuptools). + +```sh +python setup.py install --user +``` +(or `sudo python setup.py install` to install the package for all users) + +Then import the package: +```python +import signrequest_python_client +``` + +## Getting Started + +Please follow the [installation procedure](#installation--usage) and then run the following: + +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +signrequest_python_client.configuration = signrequest_python_client.Configuration() +signrequest_python_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY' +signrequest_python_client.configuration.api_key_prefix['Authorization'] = 'Token' +# create an instance of the API class +api_instance = signrequest_python_client.ApiTokensApi() +data = signrequest_python_client.AuthToken() # AuthToken | + +try: + # Create an API token + api_response = api_instance.api_tokens_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling ApiTokensApi->api_tokens_create: %s\n" % e) + +``` + +## Documentation for API Endpoints + +All URIs are relative to *https://signrequest.com/api/v1* + +Class | Method | HTTP request | Description +------------ | ------------- | ------------- | ------------- +*ApiTokensApi* | [**api_tokens_create**](docs/ApiTokensApi.md#api_tokens_create) | **POST** /api-tokens/ | Create an API token +*ApiTokensApi* | [**api_tokens_delete**](docs/ApiTokensApi.md#api_tokens_delete) | **DELETE** /api-tokens/{key}/ | Delete an API token +*ApiTokensApi* | [**api_tokens_list**](docs/ApiTokensApi.md#api_tokens_list) | **GET** /api-tokens/ | Retrieve a list of API tokens +*ApiTokensApi* | [**api_tokens_read**](docs/ApiTokensApi.md#api_tokens_read) | **GET** /api-tokens/{key}/ | Retrieve an API token +*DocumentAttachmentsApi* | [**document_attachments_create**](docs/DocumentAttachmentsApi.md#document_attachments_create) | **POST** /document-attachments/ | Create a Document Attachment +*DocumentAttachmentsApi* | [**document_attachments_list**](docs/DocumentAttachmentsApi.md#document_attachments_list) | **GET** /document-attachments/ | Retrieve a list of Document Attachments +*DocumentAttachmentsApi* | [**document_attachments_read**](docs/DocumentAttachmentsApi.md#document_attachments_read) | **GET** /document-attachments/{uuid}/ | Retrieve a Document Attachment +*DocumentsApi* | [**documents_create**](docs/DocumentsApi.md#documents_create) | **POST** /documents/ | Create a Document +*DocumentsApi* | [**documents_delete**](docs/DocumentsApi.md#documents_delete) | **DELETE** /documents/{uuid}/ | Delete a Document +*DocumentsApi* | [**documents_list**](docs/DocumentsApi.md#documents_list) | **GET** /documents/ | Retrieve a list of Documents +*DocumentsApi* | [**documents_read**](docs/DocumentsApi.md#documents_read) | **GET** /documents/{uuid}/ | Retrieve a Document +*DocumentsSearchApi* | [**documents_search_list**](docs/DocumentsSearchApi.md#documents_search_list) | **GET** /documents-search/ | Search documents +*EventsApi* | [**events_list**](docs/EventsApi.md#events_list) | **GET** /events/ | Retrieve a list of Events +*EventsApi* | [**events_read**](docs/EventsApi.md#events_read) | **GET** /events/{id}/ | Retrieve an Event +*SignrequestQuickCreateApi* | [**signrequest_quick_create_create**](docs/SignrequestQuickCreateApi.md#signrequest_quick_create_create) | **POST** /signrequest-quick-create/ | Quick create a SignRequest +*SignrequestsApi* | [**signrequests_cancel_signrequest**](docs/SignrequestsApi.md#signrequests_cancel_signrequest) | **POST** /signrequests/{uuid}/cancel_signrequest/ | Cancel a SignRequest +*SignrequestsApi* | [**signrequests_create**](docs/SignrequestsApi.md#signrequests_create) | **POST** /signrequests/ | Create a SignRequest +*SignrequestsApi* | [**signrequests_list**](docs/SignrequestsApi.md#signrequests_list) | **GET** /signrequests/ | Retrieve a list of SignRequests +*SignrequestsApi* | [**signrequests_read**](docs/SignrequestsApi.md#signrequests_read) | **GET** /signrequests/{uuid}/ | Retrieve a SignRequest +*SignrequestsApi* | [**signrequests_resend_signrequest_email**](docs/SignrequestsApi.md#signrequests_resend_signrequest_email) | **POST** /signrequests/{uuid}/resend_signrequest_email/ | Resend a SignRequest +*TeamMembersApi* | [**team_members_list**](docs/TeamMembersApi.md#team_members_list) | **GET** /team-members/ | Retrieve a list of Team Members +*TeamMembersApi* | [**team_members_read**](docs/TeamMembersApi.md#team_members_read) | **GET** /team-members/{uuid}/ | Retrieve a Team Member +*TeamsApi* | [**teams_create**](docs/TeamsApi.md#teams_create) | **POST** /teams/ | Create a Team +*TeamsApi* | [**teams_invite_member**](docs/TeamsApi.md#teams_invite_member) | **POST** /teams/{subdomain}/invite_member/ | Invite a Team Member +*TeamsApi* | [**teams_list**](docs/TeamsApi.md#teams_list) | **GET** /teams/ | Retrieve a list of Teams +*TeamsApi* | [**teams_partial_update**](docs/TeamsApi.md#teams_partial_update) | **PATCH** /teams/{subdomain}/ | Update a Team +*TeamsApi* | [**teams_read**](docs/TeamsApi.md#teams_read) | **GET** /teams/{subdomain}/ | Retrieve a Team +*TemplatesApi* | [**templates_list**](docs/TemplatesApi.md#templates_list) | **GET** /templates/ | Retrieve a list of Templates +*TemplatesApi* | [**templates_read**](docs/TemplatesApi.md#templates_read) | **GET** /templates/{uuid}/ | Retrieve a Template +*WebhooksApi* | [**webhooks_create**](docs/WebhooksApi.md#webhooks_create) | **POST** /webhooks/ | Create a Webhook +*WebhooksApi* | [**webhooks_delete**](docs/WebhooksApi.md#webhooks_delete) | **DELETE** /webhooks/{uuid}/ | Delete a Webhook +*WebhooksApi* | [**webhooks_list**](docs/WebhooksApi.md#webhooks_list) | **GET** /webhooks/ | Retrieve a list of Webhooks +*WebhooksApi* | [**webhooks_partial_update**](docs/WebhooksApi.md#webhooks_partial_update) | **PATCH** /webhooks/{uuid}/ | Partially update a Webhook +*WebhooksApi* | [**webhooks_read**](docs/WebhooksApi.md#webhooks_read) | **GET** /webhooks/{uuid}/ | Retrieve a Webhook +*WebhooksApi* | [**webhooks_update**](docs/WebhooksApi.md#webhooks_update) | **PUT** /webhooks/{uuid}/ | Update a Webhook + + +## Documentation For Models + + - [AuthToken](docs/AuthToken.md) + - [Document](docs/Document.md) + - [DocumentAttachment](docs/DocumentAttachment.md) + - [DocumentSearch](docs/DocumentSearch.md) + - [DocumentSignerTemplateConf](docs/DocumentSignerTemplateConf.md) + - [Event](docs/Event.md) + - [FileFromSf](docs/FileFromSf.md) + - [InlineDocumentSignerIntegrationData](docs/InlineDocumentSignerIntegrationData.md) + - [InlineIntegrationData](docs/InlineIntegrationData.md) + - [InlinePrefillTags](docs/InlinePrefillTags.md) + - [InlineResponse200](docs/InlineResponse200.md) + - [InlineResponse2001](docs/InlineResponse2001.md) + - [InlineResponse2002](docs/InlineResponse2002.md) + - [InlineResponse2003](docs/InlineResponse2003.md) + - [InlineResponse2004](docs/InlineResponse2004.md) + - [InlineResponse2005](docs/InlineResponse2005.md) + - [InlineResponse2006](docs/InlineResponse2006.md) + - [InlineResponse2007](docs/InlineResponse2007.md) + - [InlineResponse2008](docs/InlineResponse2008.md) + - [InlineResponse2009](docs/InlineResponse2009.md) + - [InlineSignRequest](docs/InlineSignRequest.md) + - [InlineTeam](docs/InlineTeam.md) + - [InlineTeamMember](docs/InlineTeamMember.md) + - [InviteMember](docs/InviteMember.md) + - [Placeholder](docs/Placeholder.md) + - [RequiredAttachment](docs/RequiredAttachment.md) + - [SignRequest](docs/SignRequest.md) + - [SignRequestQuickCreate](docs/SignRequestQuickCreate.md) + - [Signer](docs/Signer.md) + - [SignerAttachment](docs/SignerAttachment.md) + - [SignerInputs](docs/SignerInputs.md) + - [SigningLog](docs/SigningLog.md) + - [Team](docs/Team.md) + - [TeamMember](docs/TeamMember.md) + - [Template](docs/Template.md) + - [User](docs/User.md) + - [WebhookSubscription](docs/WebhookSubscription.md) + + +## Documentation For Authorization + + +## Token + +- **Type**: API key +- **API key parameter name**: Authorization +- **Location**: HTTP header + + +## Author + +tech-support@signrequest.com + diff --git a/docs/ApiTokensApi.md b/docs/ApiTokensApi.md new file mode 100644 index 0000000..208ae4b --- /dev/null +++ b/docs/ApiTokensApi.md @@ -0,0 +1,225 @@ +# signrequest_python_client.ApiTokensApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**api_tokens_create**](ApiTokensApi.md#api_tokens_create) | **POST** /api-tokens/ | Create an API token +[**api_tokens_delete**](ApiTokensApi.md#api_tokens_delete) | **DELETE** /api-tokens/{key}/ | Delete an API token +[**api_tokens_list**](ApiTokensApi.md#api_tokens_list) | **GET** /api-tokens/ | Retrieve a list of API tokens +[**api_tokens_read**](ApiTokensApi.md#api_tokens_read) | **GET** /api-tokens/{key}/ | Retrieve an API token + + +# **api_tokens_create** +> AuthToken api_tokens_create(data) + +Create an API token + +You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.AuthToken() # AuthToken | + +try: + # Create an API token + api_response = api_instance.api_tokens_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling ApiTokensApi->api_tokens_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**AuthToken**](AuthToken.md)| | + +### Return type + +[**AuthToken**](AuthToken.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **api_tokens_delete** +> api_tokens_delete(key) + +Delete an API token + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +key = 'key_example' # str | A unique value identifying this api token. + +try: + # Delete an API token + api_instance.api_tokens_delete(key) +except ApiException as e: + print("Exception when calling ApiTokensApi->api_tokens_delete: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **key** | **str**| A unique value identifying this api token. | + +### Return type + +void (empty response body) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **api_tokens_list** +> InlineResponse200 api_tokens_list(page=page, limit=limit) + +Retrieve a list of API tokens + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of API tokens + api_response = api_instance.api_tokens_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling ApiTokensApi->api_tokens_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse200**](InlineResponse200.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **api_tokens_read** +> AuthToken api_tokens_read(key) + +Retrieve an API token + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +key = 'key_example' # str | A unique value identifying this api token. + +try: + # Retrieve an API token + api_response = api_instance.api_tokens_read(key) + pprint(api_response) +except ApiException as e: + print("Exception when calling ApiTokensApi->api_tokens_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **key** | **str**| A unique value identifying this api token. | + +### Return type + +[**AuthToken**](AuthToken.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/AuthToken.md b/docs/AuthToken.md new file mode 100644 index 0000000..29373e6 --- /dev/null +++ b/docs/AuthToken.md @@ -0,0 +1,15 @@ +# AuthToken + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**email** | **str** | | [optional] +**password** | **str** | | [optional] +**subdomain** | **str** | | +**name** | **str** | | [optional] +**key** | **str** | | [optional] +**url** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/Document.md b/docs/Document.md new file mode 100644 index 0000000..cd6afe9 --- /dev/null +++ b/docs/Document.md @@ -0,0 +1,33 @@ +# Document + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**url** | **str** | | [optional] +**uuid** | **str** | | [optional] +**user** | [**User**](User.md) | | [optional] +**file_as_pdf** | **str** | Temporary URL to original file as PDF, expires in five minutes | [optional] +**name** | **str** | Defaults to filename, including extension | [optional] +**external_id** | **str** | ID used to reference document in external system | [optional] +**frontend_id** | **str** | Shared secret used in conjunction with <a href=\"#section/Frontend-API/SignRequest-js-client-(beta)\">SignRequest-js client</a> to grant user access to a document that's not a member of the document's team | [optional] +**file** | **str** | Temporary URL to original file, expires in five minutes | [optional] +**file_from_url** | **str** | Publicly accessible URL of document to be downloaded by SignRequest | [optional] +**events_callback_url** | **str** | URL at which to receive [event callbacks](#section/Events/Events-callback) for this document | [optional] +**file_from_content** | **str** | Base64 encoded document content | [optional] +**file_from_content_name** | **str** | Filename, including extension. Required when using `file_from_content`. | [optional] +**template** | **str** | | [optional] +**prefill_tags** | [**list[InlinePrefillTags]**](InlinePrefillTags.md) | Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) | [optional] +**integrations** | [**list[InlineIntegrationData]**](InlineIntegrationData.md) | | [optional] +**file_from_sf** | [**FileFromSf**](FileFromSf.md) | | [optional] +**auto_delete_days** | **int** | Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted | [optional] +**pdf** | **str** | Temporary URL to signed document as PDF, expires in five minutes | [optional] +**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] +**signrequest** | [**InlineSignRequest**](InlineSignRequest.md) | | [optional] +**api_used** | **bool** | Indicates whether document was created using the API | [optional] +**security_hash** | **str** | SHA256 hash of PDF contents | [optional] +**attachments** | [**list[DocumentAttachment]**](DocumentAttachment.md) | | [optional] +**auto_delete_after** | **datetime** | Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/DocumentAttachment.md b/docs/DocumentAttachment.md new file mode 100644 index 0000000..f7d1f15 --- /dev/null +++ b/docs/DocumentAttachment.md @@ -0,0 +1,17 @@ +# DocumentAttachment + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**url** | **str** | | [optional] +**uuid** | **str** | | [optional] +**name** | **str** | Defaults to filename | [optional] +**file** | **str** | Temporary URL to document attachment, expires in five minutes | [optional] +**file_from_content** | **str** | Base64 encoded document content | [optional] +**file_from_content_name** | **str** | Filename, including extension. Required when using `file_from_content`. | [optional] +**file_from_url** | **str** | Publicly accessible URL of document to be downloaded by SignRequest | [optional] +**document** | **str** | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/DocumentAttachmentsApi.md b/docs/DocumentAttachmentsApi.md new file mode 100644 index 0000000..b578c85 --- /dev/null +++ b/docs/DocumentAttachmentsApi.md @@ -0,0 +1,173 @@ +# signrequest_python_client.DocumentAttachmentsApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**document_attachments_create**](DocumentAttachmentsApi.md#document_attachments_create) | **POST** /document-attachments/ | Create a Document Attachment +[**document_attachments_list**](DocumentAttachmentsApi.md#document_attachments_list) | **GET** /document-attachments/ | Retrieve a list of Document Attachments +[**document_attachments_read**](DocumentAttachmentsApi.md#document_attachments_read) | **GET** /document-attachments/{uuid}/ | Retrieve a Document Attachment + + +# **document_attachments_create** +> DocumentAttachment document_attachments_create(data) + +Create a Document Attachment + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.DocumentAttachment() # DocumentAttachment | + +try: + # Create a Document Attachment + api_response = api_instance.document_attachments_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentAttachmentsApi->document_attachments_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**DocumentAttachment**](DocumentAttachment.md)| | + +### Return type + +[**DocumentAttachment**](DocumentAttachment.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **document_attachments_list** +> InlineResponse2001 document_attachments_list(page=page, limit=limit) + +Retrieve a list of Document Attachments + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed +# configuration.api_key_prefix['Authorization'] = 'Bearer' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Document Attachments + api_response = api_instance.document_attachments_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentAttachmentsApi->document_attachments_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2001**](InlineResponse2001.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **document_attachments_read** +> DocumentAttachment document_attachments_read(uuid) + +Retrieve a Document Attachment + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a Document Attachment + api_response = api_instance.document_attachments_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentAttachmentsApi->document_attachments_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**DocumentAttachment**](DocumentAttachment.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/DocumentSearch.md b/docs/DocumentSearch.md new file mode 100644 index 0000000..5e868e1 --- /dev/null +++ b/docs/DocumentSearch.md @@ -0,0 +1,24 @@ +# DocumentSearch + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] +**name** | **str** | Defaults to filename | [optional] +**who** | **str** | | +**nr_extra_docs** | **int** | | +**from_email** | **str** | | +**parent_doc** | **str** | | +**uuid** | **str** | | [optional] +**created** | **datetime** | | [optional] +**autocomplete** | **str** | | +**finished_on** | **datetime** | | +**subdomain** | **str** | | +**signer_emails** | **list[str]** | | [optional] +**status_display** | **str** | | [optional] +**created_timestamp** | **int** | | [optional] +**finished_on_timestamp** | **int** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/DocumentSignerTemplateConf.md b/docs/DocumentSignerTemplateConf.md new file mode 100644 index 0000000..2a28d89 --- /dev/null +++ b/docs/DocumentSignerTemplateConf.md @@ -0,0 +1,16 @@ +# DocumentSignerTemplateConf + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**signer_index** | **int** | | [optional] +**needs_to_sign** | **bool** | | [optional] +**approve_only** | **bool** | | [optional] +**notify_only** | **bool** | | [optional] +**in_person** | **bool** | | [optional] +**order** | **int** | | [optional] +**placeholders** | [**list[Placeholder]**](Placeholder.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/DocumentsApi.md b/docs/DocumentsApi.md new file mode 100644 index 0000000..3889217 --- /dev/null +++ b/docs/DocumentsApi.md @@ -0,0 +1,225 @@ +# signrequest_python_client.DocumentsApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**documents_create**](DocumentsApi.md#documents_create) | **POST** /documents/ | Create a Document +[**documents_delete**](DocumentsApi.md#documents_delete) | **DELETE** /documents/{uuid}/ | Delete a Document +[**documents_list**](DocumentsApi.md#documents_list) | **GET** /documents/ | Retrieve a list of Documents +[**documents_read**](DocumentsApi.md#documents_read) | **GET** /documents/{uuid}/ | Retrieve a Document + + +# **documents_create** +> Document documents_create(data) + +Create a Document + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.Document() # Document | + +try: + # Create a Document + api_response = api_instance.documents_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentsApi->documents_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**Document**](Document.md)| | + +### Return type + +[**Document**](Document.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **documents_delete** +> documents_delete(uuid) + +Delete a Document + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Delete a Document + api_instance.documents_delete(uuid) +except ApiException as e: + print("Exception when calling DocumentsApi->documents_delete: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +void (empty response body) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **documents_list** +> InlineResponse2003 documents_list(page=page, limit=limit) + +Retrieve a list of Documents + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Documents + api_response = api_instance.documents_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentsApi->documents_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2003**](InlineResponse2003.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **documents_read** +> Document documents_read(uuid) + +Retrieve a Document + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a Document + api_response = api_instance.documents_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentsApi->documents_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**Document**](Document.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/DocumentsSearchApi.md b/docs/DocumentsSearchApi.md new file mode 100644 index 0000000..459f9fa --- /dev/null +++ b/docs/DocumentsSearchApi.md @@ -0,0 +1,64 @@ +# signrequest_python_client.DocumentsSearchApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**documents_search_list**](DocumentsSearchApi.md#documents_search_list) | **GET** /documents-search/ | Search documents + + +# **documents_search_list** +> InlineResponse2002 documents_search_list(page=page, limit=limit) + +Search documents + +Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.DocumentsSearchApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Search documents + api_response = api_instance.documents_search_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling DocumentsSearchApi->documents_search_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2002**](InlineResponse2002.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json, text/csv, application/vnd.ms-excel + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/Event.md b/docs/Event.md new file mode 100644 index 0000000..69d13e9 --- /dev/null +++ b/docs/Event.md @@ -0,0 +1,18 @@ +# Event + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**uuid** | **str** | | [optional] +**status** | **str** | | [optional] +**event_type** | **str** | | [optional] +**delivered** | **bool** | | [optional] +**delivered_on** | **datetime** | | [optional] +**callback_status_code** | **int** | | [optional] +**timestamp** | **datetime** | | [optional] +**document** | [**Document**](Document.md) | | [optional] +**signer** | [**Signer**](Signer.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/EventsApi.md b/docs/EventsApi.md new file mode 100644 index 0000000..aa10ccb --- /dev/null +++ b/docs/EventsApi.md @@ -0,0 +1,144 @@ +# signrequest_python_client.EventsApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**events_list**](EventsApi.md#events_list) | **GET** /events/ | Retrieve a list of Events +[**events_read**](EventsApi.md#events_read) | **GET** /events/{id}/ | Retrieve an Event + + +# **events_list** +> InlineResponse2004 events_list(document__uuid=document__uuid, document__external_id=document__external_id, document__signrequest__who=document__signrequest__who, document__signrequest__from_email=document__signrequest__from_email, document__status=document__status, document__user__email=document__user__email, document__user__first_name=document__user__first_name, document__user__last_name=document__user__last_name, delivered=delivered, delivered_on=delivered_on, timestamp=timestamp, status=status, event_type=event_type, page=page, limit=limit) + +Retrieve a list of Events + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.EventsApi(signrequest_python_client.ApiClient(configuration)) +document__uuid = 'document__uuid_example' # str | (optional) +document__external_id = 'document__external_id_example' # str | (optional) +document__signrequest__who = 'document__signrequest__who_example' # str | (optional) +document__signrequest__from_email = 'document__signrequest__from_email_example' # str | (optional) +document__status = 'document__status_example' # str | (optional) +document__user__email = 'document__user__email_example' # str | (optional) +document__user__first_name = 'document__user__first_name_example' # str | (optional) +document__user__last_name = 'document__user__last_name_example' # str | (optional) +delivered = 'delivered_example' # str | (optional) +delivered_on = 'delivered_on_example' # str | (optional) +timestamp = 'timestamp_example' # str | (optional) +status = 'status_example' # str | (optional) +event_type = 'event_type_example' # str | (optional) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Events + api_response = api_instance.events_list(document__uuid=document__uuid, document__external_id=document__external_id, document__signrequest__who=document__signrequest__who, document__signrequest__from_email=document__signrequest__from_email, document__status=document__status, document__user__email=document__user__email, document__user__first_name=document__user__first_name, document__user__last_name=document__user__last_name, delivered=delivered, delivered_on=delivered_on, timestamp=timestamp, status=status, event_type=event_type, page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling EventsApi->events_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **document__uuid** | **str**| | [optional] + **document__external_id** | **str**| | [optional] + **document__signrequest__who** | **str**| | [optional] + **document__signrequest__from_email** | **str**| | [optional] + **document__status** | **str**| | [optional] + **document__user__email** | **str**| | [optional] + **document__user__first_name** | **str**| | [optional] + **document__user__last_name** | **str**| | [optional] + **delivered** | **str**| | [optional] + **delivered_on** | **str**| | [optional] + **timestamp** | **str**| | [optional] + **status** | **str**| | [optional] + **event_type** | **str**| | [optional] + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2004**](InlineResponse2004.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **events_read** +> Event events_read(id) + +Retrieve an Event + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.EventsApi(signrequest_python_client.ApiClient(configuration)) +id = 56 # int | A unique integer value identifying this event. + +try: + # Retrieve an Event + api_response = api_instance.events_read(id) + pprint(api_response) +except ApiException as e: + print("Exception when calling EventsApi->events_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **id** | **int**| A unique integer value identifying this event. | + +### Return type + +[**Event**](Event.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/FileFromSf.md b/docs/FileFromSf.md new file mode 100644 index 0000000..bf49342 --- /dev/null +++ b/docs/FileFromSf.md @@ -0,0 +1,11 @@ +# FileFromSf + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**object_type** | **str** | | +**object_id** | **str** | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineDocumentSignerIntegrationData.md b/docs/InlineDocumentSignerIntegrationData.md new file mode 100644 index 0000000..81c644a --- /dev/null +++ b/docs/InlineDocumentSignerIntegrationData.md @@ -0,0 +1,11 @@ +# InlineDocumentSignerIntegrationData + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**integration** | **str** | | [optional] +**integration_data** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineIntegrationData.md b/docs/InlineIntegrationData.md new file mode 100644 index 0000000..81ece44 --- /dev/null +++ b/docs/InlineIntegrationData.md @@ -0,0 +1,11 @@ +# InlineIntegrationData + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**integration** | **str** | | [optional] +**integration_data** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlinePrefillTags.md b/docs/InlinePrefillTags.md new file mode 100644 index 0000000..2458988 --- /dev/null +++ b/docs/InlinePrefillTags.md @@ -0,0 +1,13 @@ +# InlinePrefillTags + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**external_id** | **str** | | [optional] +**text** | **str** | | [optional] +**checkbox_value** | **bool** | | [optional] +**date_value** | **date** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse200.md b/docs/InlineResponse200.md new file mode 100644 index 0000000..3da8d95 --- /dev/null +++ b/docs/InlineResponse200.md @@ -0,0 +1,13 @@ +# InlineResponse200 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[AuthToken]**](AuthToken.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2001.md b/docs/InlineResponse2001.md new file mode 100644 index 0000000..1c40ccd --- /dev/null +++ b/docs/InlineResponse2001.md @@ -0,0 +1,13 @@ +# InlineResponse2001 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[DocumentAttachment]**](DocumentAttachment.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2002.md b/docs/InlineResponse2002.md new file mode 100644 index 0000000..6cfdc22 --- /dev/null +++ b/docs/InlineResponse2002.md @@ -0,0 +1,13 @@ +# InlineResponse2002 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[DocumentSearch]**](DocumentSearch.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2003.md b/docs/InlineResponse2003.md new file mode 100644 index 0000000..1746f75 --- /dev/null +++ b/docs/InlineResponse2003.md @@ -0,0 +1,13 @@ +# InlineResponse2003 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[Document]**](Document.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2004.md b/docs/InlineResponse2004.md new file mode 100644 index 0000000..c2f0a14 --- /dev/null +++ b/docs/InlineResponse2004.md @@ -0,0 +1,13 @@ +# InlineResponse2004 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[Event]**](Event.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2005.md b/docs/InlineResponse2005.md new file mode 100644 index 0000000..916c0c1 --- /dev/null +++ b/docs/InlineResponse2005.md @@ -0,0 +1,13 @@ +# InlineResponse2005 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[SignRequest]**](SignRequest.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2006.md b/docs/InlineResponse2006.md new file mode 100644 index 0000000..95b0603 --- /dev/null +++ b/docs/InlineResponse2006.md @@ -0,0 +1,13 @@ +# InlineResponse2006 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[TeamMember]**](TeamMember.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2007.md b/docs/InlineResponse2007.md new file mode 100644 index 0000000..1926382 --- /dev/null +++ b/docs/InlineResponse2007.md @@ -0,0 +1,13 @@ +# InlineResponse2007 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[Team]**](Team.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2008.md b/docs/InlineResponse2008.md new file mode 100644 index 0000000..3f4c7a8 --- /dev/null +++ b/docs/InlineResponse2008.md @@ -0,0 +1,13 @@ +# InlineResponse2008 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[Template]**](Template.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2009.md b/docs/InlineResponse2009.md new file mode 100644 index 0000000..137e5c9 --- /dev/null +++ b/docs/InlineResponse2009.md @@ -0,0 +1,13 @@ +# InlineResponse2009 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**count** | **int** | | +**next** | **str** | | [optional] +**previous** | **str** | | [optional] +**results** | [**list[WebhookSubscription]**](WebhookSubscription.md) | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineSignRequest.md b/docs/InlineSignRequest.md new file mode 100644 index 0000000..048d02f --- /dev/null +++ b/docs/InlineSignRequest.md @@ -0,0 +1,27 @@ +# InlineSignRequest + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**from_email** | **str** | Email of user sending the SignRequest (must be a validated email) | +**from_email_name** | **str** | Name to be used in the `From` email header, e.g. `{from_email_name} <no-reply@signrequest.com>` | [optional] +**is_being_prepared** | **bool** | Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) | [optional] +**prepare_url** | **str** | | [optional] +**redirect_url** | **str** | URL at which SignRequest will redirect to when a document is signed | [optional] +**required_attachments** | [**list[RequiredAttachment]**](RequiredAttachment.md) | | [optional] +**disable_attachments** | **bool** | Disable uploading/adding of attachments | [optional] +**disable_text_signatures** | **bool** | Disable usage of signatures generated by typing (text) | [optional] +**disable_text** | **bool** | Disable adding of text | [optional] +**disable_date** | **bool** | Disable adding of dates | [optional] +**disable_emails** | **bool** | Disable all SignRequest status emails as well as the email that contains the signed documents | [optional] +**disable_upload_signatures** | **bool** | Disable usage of uploaded signatures (images) | [optional] +**subject** | **str** | Subject of SignRequest email | [optional] +**message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] +**who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] +**send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] +**signers** | [**list[Signer]**](Signer.md) | | +**uuid** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineTeam.md b/docs/InlineTeam.md new file mode 100644 index 0000000..2da3fdf --- /dev/null +++ b/docs/InlineTeam.md @@ -0,0 +1,12 @@ +# InlineTeam + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**name** | **str** | | [optional] +**subdomain** | **str** | | [optional] +**url** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineTeamMember.md b/docs/InlineTeamMember.md new file mode 100644 index 0000000..96dbdfc --- /dev/null +++ b/docs/InlineTeamMember.md @@ -0,0 +1,15 @@ +# InlineTeamMember + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**uuid** | **str** | | [optional] +**url** | **str** | | [optional] +**user** | [**User**](User.md) | | [optional] +**is_admin** | **bool** | | [optional] +**is_active** | **bool** | | [optional] +**is_owner** | **bool** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InviteMember.md b/docs/InviteMember.md new file mode 100644 index 0000000..e4554e2 --- /dev/null +++ b/docs/InviteMember.md @@ -0,0 +1,12 @@ +# InviteMember + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**email** | **str** | | +**is_admin** | **bool** | | [optional] [default to False] +**is_owner** | **bool** | | [optional] [default to False] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/Placeholder.md b/docs/Placeholder.md new file mode 100644 index 0000000..e2319f3 --- /dev/null +++ b/docs/Placeholder.md @@ -0,0 +1,17 @@ +# Placeholder + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**uuid** | **str** | | [optional] +**type** | **str** | | [optional] +**page_index** | **int** | | +**prefill** | **bool** | | +**text** | **str** | | [optional] +**checkbox_value** | **bool** | | [optional] +**date_value** | **date** | | [optional] +**external_id** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/RequiredAttachment.md b/docs/RequiredAttachment.md new file mode 100644 index 0000000..c5fb963 --- /dev/null +++ b/docs/RequiredAttachment.md @@ -0,0 +1,11 @@ +# RequiredAttachment + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**name** | **str** | | +**uuid** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignRequest.md b/docs/SignRequest.md new file mode 100644 index 0000000..6cd76d4 --- /dev/null +++ b/docs/SignRequest.md @@ -0,0 +1,31 @@ +# SignRequest + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**from_email** | **str** | Email of user sending the SignRequest (must be a validated email) | [optional] +**from_email_name** | **str** | Name to be used in the `From` email header, e.g. `{from_email_name} <no-reply@signrequest.com>` | [optional] +**is_being_prepared** | **bool** | Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) | [optional] +**prepare_url** | **str** | | [optional] +**redirect_url** | **str** | URL at which SignRequest will redirect to when a document is signed | [optional] +**required_attachments** | [**list[RequiredAttachment]**](RequiredAttachment.md) | Attachments that signers are required to upload | [optional] +**disable_attachments** | **bool** | Disable uploading/adding of attachments | [optional] +**disable_text_signatures** | **bool** | Disable usage of signatures generated by typing (text) | [optional] +**disable_text** | **bool** | Disable adding of text | [optional] +**disable_date** | **bool** | Disable adding of dates | [optional] +**disable_emails** | **bool** | Disable all SignRequest status emails as well as the email that contains the signed documents | [optional] +**disable_upload_signatures** | **bool** | Disable usage of uploaded signatures (images) | [optional] +**subject** | **str** | Subject of SignRequest email | [optional] +**message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] +**who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] +**send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] +**signers** | [**list[Signer]**](Signer.md) | | +**uuid** | **str** | | [optional] +**url** | **str** | | [optional] +**document** | **str** | | +**integration** | **str** | | [optional] +**integration_data** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignRequestQuickCreate.md b/docs/SignRequestQuickCreate.md new file mode 100644 index 0000000..57f1ac3 --- /dev/null +++ b/docs/SignRequestQuickCreate.md @@ -0,0 +1,44 @@ +# SignRequestQuickCreate + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**from_email** | **str** | Email of user sending the SignRequest (must be a validated email) | [optional] +**from_email_name** | **str** | Name to be used in the `From` email header, e.g. `{from_email_name} <no-reply@signrequest.com>` | [optional] +**is_being_prepared** | **bool** | Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) | [optional] +**prepare_url** | **str** | | [optional] +**redirect_url** | **str** | URL at which SignRequest will redirect to when a document is signed | [optional] +**required_attachments** | [**list[RequiredAttachment]**](RequiredAttachment.md) | Attachments that signers are required to upload | [optional] +**disable_attachments** | **bool** | Disable uploading/adding of attachments | [optional] +**disable_text_signatures** | **bool** | Disable usage of signatures generated by typing (text) | [optional] +**disable_text** | **bool** | Disable adding of text | [optional] +**disable_date** | **bool** | Disable adding of dates | [optional] +**disable_emails** | **bool** | Disable all SignRequest status emails as well as the email that contains the signed documents | [optional] +**disable_upload_signatures** | **bool** | Disable usage of uploaded signatures (images) | [optional] +**subject** | **str** | Subject of SignRequest email | [optional] +**message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] +**who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] +**send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] +**signers** | [**list[Signer]**](Signer.md) | | +**uuid** | **str** | | [optional] +**url** | **str** | | [optional] +**document** | **str** | | [optional] +**integration** | **str** | | [optional] +**integration_data** | **str** | | [optional] +**name** | **str** | Defaults to filename, including extension | [optional] +**external_id** | **str** | ID used to reference document in external system | [optional] +**frontend_id** | **str** | Shared secret used in conjunction with <a href=\"#section/Frontend-API/SignRequest-js-client-(beta)\">SignRequest-js client</a> to grant user access to a document that's not a member of the document's team | [optional] +**file** | **str** | Temporary URL to original file, expires in five minutes | [optional] +**file_from_url** | **str** | Publicly accessible URL of document to be downloaded by SignRequest | [optional] +**events_callback_url** | **str** | URL at which to receive [event callbacks](#section/Events/Events-callback) for this document | [optional] +**file_from_content** | **str** | Base64 encoded document content | [optional] +**file_from_content_name** | **str** | Filename, including extension. Required when using `file_from_content`. | [optional] +**template** | **str** | | [optional] +**prefill_tags** | [**list[InlinePrefillTags]**](InlinePrefillTags.md) | Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) | [optional] +**integrations** | [**list[InlineIntegrationData]**](InlineIntegrationData.md) | | [optional] +**file_from_sf** | [**FileFromSf**](FileFromSf.md) | | [optional] +**auto_delete_days** | **int** | Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/Signer.md b/docs/Signer.md new file mode 100644 index 0000000..2016aac --- /dev/null +++ b/docs/Signer.md @@ -0,0 +1,42 @@ +# Signer + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**email** | **str** | | +**display_name** | **str** | | [optional] +**first_name** | **str** | | [optional] +**last_name** | **str** | | [optional] +**email_viewed** | **bool** | | [optional] +**viewed** | **bool** | | [optional] +**signed** | **bool** | | [optional] +**downloaded** | **bool** | | [optional] +**signed_on** | **datetime** | | [optional] +**needs_to_sign** | **bool** | | [optional] [default to True] +**approve_only** | **bool** | | [optional] +**notify_only** | **bool** | | [optional] +**in_person** | **bool** | | [optional] +**order** | **int** | | [optional] +**language** | **str** | | [optional] +**force_language** | **bool** | | [optional] +**emailed** | **bool** | | [optional] +**verify_phone_number** | **str** | | [optional] +**verify_bank_account** | **str** | | [optional] +**declined** | **bool** | | [optional] +**declined_on** | **datetime** | | [optional] +**forwarded** | **str** | | [optional] +**forwarded_on** | **datetime** | | [optional] +**forwarded_to_email** | **str** | | [optional] +**forwarded_reason** | **str** | | [optional] +**message** | **str** | | [optional] +**embed_url_user_id** | **str** | | [optional] +**inputs** | [**list[SignerInputs]**](SignerInputs.md) | | [optional] +**embed_url** | **str** | | [optional] +**attachments** | [**list[SignerAttachment]**](SignerAttachment.md) | | [optional] +**redirect_url** | **str** | | [optional] +**after_document** | **str** | | [optional] +**integrations** | [**list[InlineDocumentSignerIntegrationData]**](InlineDocumentSignerIntegrationData.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignerAttachment.md b/docs/SignerAttachment.md new file mode 100644 index 0000000..6491d56 --- /dev/null +++ b/docs/SignerAttachment.md @@ -0,0 +1,13 @@ +# SignerAttachment + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**uuid** | **str** | | [optional] +**name** | **str** | Defaults to filename | [optional] +**file** | **str** | | [optional] +**for_attachment** | [**RequiredAttachment**](RequiredAttachment.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignerInputs.md b/docs/SignerInputs.md new file mode 100644 index 0000000..e2455f2 --- /dev/null +++ b/docs/SignerInputs.md @@ -0,0 +1,16 @@ +# SignerInputs + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**type** | **str** | | [optional] +**page_index** | **int** | | +**text** | **str** | | [optional] +**checkbox_value** | **bool** | | [optional] +**date_value** | **date** | | [optional] +**external_id** | **str** | | [optional] +**placeholder_uuid** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SigningLog.md b/docs/SigningLog.md new file mode 100644 index 0000000..0f7a690 --- /dev/null +++ b/docs/SigningLog.md @@ -0,0 +1,11 @@ +# SigningLog + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**pdf** | **str** | Temporary URL to signing log, expires in five minutes | [optional] +**security_hash** | **str** | SHA256 hash of PDF contents | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignrequestQuickCreateApi.md b/docs/SignrequestQuickCreateApi.md new file mode 100644 index 0000000..e6ed862 --- /dev/null +++ b/docs/SignrequestQuickCreateApi.md @@ -0,0 +1,62 @@ +# signrequest_python_client.SignrequestQuickCreateApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**signrequest_quick_create_create**](SignrequestQuickCreateApi.md#signrequest_quick_create_create) | **POST** /signrequest-quick-create/ | Quick create a SignRequest + + +# **signrequest_quick_create_create** +> SignRequestQuickCreate signrequest_quick_create_create(data) + +Quick create a SignRequest + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestQuickCreateApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.SignRequestQuickCreate() # SignRequestQuickCreate | + +try: + # Quick create a SignRequest + api_response = api_instance.signrequest_quick_create_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestQuickCreateApi->signrequest_quick_create_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**SignRequestQuickCreate**](SignRequestQuickCreate.md)| | + +### Return type + +[**SignRequestQuickCreate**](SignRequestQuickCreate.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/SignrequestsApi.md b/docs/SignrequestsApi.md new file mode 100644 index 0000000..c04ebf8 --- /dev/null +++ b/docs/SignrequestsApi.md @@ -0,0 +1,284 @@ +# signrequest_python_client.SignrequestsApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**signrequests_cancel_signrequest**](SignrequestsApi.md#signrequests_cancel_signrequest) | **POST** /signrequests/{uuid}/cancel_signrequest/ | Cancel a SignRequest +[**signrequests_create**](SignrequestsApi.md#signrequests_create) | **POST** /signrequests/ | Create a SignRequest +[**signrequests_list**](SignrequestsApi.md#signrequests_list) | **GET** /signrequests/ | Retrieve a list of SignRequests +[**signrequests_read**](SignrequestsApi.md#signrequests_read) | **GET** /signrequests/{uuid}/ | Retrieve a SignRequest +[**signrequests_resend_signrequest_email**](SignrequestsApi.md#signrequests_resend_signrequest_email) | **POST** /signrequests/{uuid}/resend_signrequest_email/ | Resend a SignRequest + + +# **signrequests_cancel_signrequest** +> SignRequest signrequests_cancel_signrequest(uuid, data) + +Cancel a SignRequest + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | +data = signrequest_python_client.SignRequest() # SignRequest | + +try: + # Cancel a SignRequest + api_response = api_instance.signrequests_cancel_signrequest(uuid, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestsApi->signrequests_cancel_signrequest: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + **data** | [**SignRequest**](SignRequest.md)| | + +### Return type + +[**SignRequest**](SignRequest.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **signrequests_create** +> SignRequest signrequests_create(data) + +Create a SignRequest + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.SignRequest() # SignRequest | + +try: + # Create a SignRequest + api_response = api_instance.signrequests_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestsApi->signrequests_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**SignRequest**](SignRequest.md)| | + +### Return type + +[**SignRequest**](SignRequest.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **signrequests_list** +> InlineResponse2005 signrequests_list(page=page, limit=limit) + +Retrieve a list of SignRequests + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of SignRequests + api_response = api_instance.signrequests_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestsApi->signrequests_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2005**](InlineResponse2005.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **signrequests_read** +> SignRequest signrequests_read(uuid) + +Retrieve a SignRequest + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a SignRequest + api_response = api_instance.signrequests_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestsApi->signrequests_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**SignRequest**](SignRequest.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **signrequests_resend_signrequest_email** +> SignRequest signrequests_resend_signrequest_email(uuid, data) + +Resend a SignRequest + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | +data = signrequest_python_client.SignRequest() # SignRequest | + +try: + # Resend a SignRequest + api_response = api_instance.signrequests_resend_signrequest_email(uuid, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling SignrequestsApi->signrequests_resend_signrequest_email: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + **data** | [**SignRequest**](SignRequest.md)| | + +### Return type + +[**SignRequest**](SignRequest.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/Team.md b/docs/Team.md new file mode 100644 index 0000000..85caa58 --- /dev/null +++ b/docs/Team.md @@ -0,0 +1,17 @@ +# Team + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**name** | **str** | | +**subdomain** | **str** | | +**url** | **str** | | [optional] +**logo** | **str** | | [optional] +**phone** | **str** | | [optional] +**primary_color** | **str** | | [optional] +**events_callback_url** | **str** | | [optional] +**members** | [**list[InlineTeamMember]**](InlineTeamMember.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/TeamMember.md b/docs/TeamMember.md new file mode 100644 index 0000000..29edabd --- /dev/null +++ b/docs/TeamMember.md @@ -0,0 +1,15 @@ +# TeamMember + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**uuid** | **str** | | [optional] +**url** | **str** | | [optional] +**user** | [**User**](User.md) | | [optional] +**is_admin** | **bool** | | [optional] +**is_active** | **bool** | | [optional] +**is_owner** | **bool** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/TeamMembersApi.md b/docs/TeamMembersApi.md new file mode 100644 index 0000000..fab2514 --- /dev/null +++ b/docs/TeamMembersApi.md @@ -0,0 +1,130 @@ +# signrequest_python_client.TeamMembersApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**team_members_list**](TeamMembersApi.md#team_members_list) | **GET** /team-members/ | Retrieve a list of Team Members +[**team_members_read**](TeamMembersApi.md#team_members_read) | **GET** /team-members/{uuid}/ | Retrieve a Team Member + + +# **team_members_list** +> InlineResponse2006 team_members_list(is_active=is_active, is_owner=is_owner, is_admin=is_admin, user__email=user__email, user__first_name=user__first_name, user__last_name=user__last_name, page=page, limit=limit) + +Retrieve a list of Team Members + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamMembersApi(signrequest_python_client.ApiClient(configuration)) +is_active = 'is_active_example' # str | (optional) +is_owner = 'is_owner_example' # str | (optional) +is_admin = 'is_admin_example' # str | (optional) +user__email = 'user__email_example' # str | (optional) +user__first_name = 'user__first_name_example' # str | (optional) +user__last_name = 'user__last_name_example' # str | (optional) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Team Members + api_response = api_instance.team_members_list(is_active=is_active, is_owner=is_owner, is_admin=is_admin, user__email=user__email, user__first_name=user__first_name, user__last_name=user__last_name, page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamMembersApi->team_members_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **is_active** | **str**| | [optional] + **is_owner** | **str**| | [optional] + **is_admin** | **str**| | [optional] + **user__email** | **str**| | [optional] + **user__first_name** | **str**| | [optional] + **user__last_name** | **str**| | [optional] + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2006**](InlineResponse2006.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **team_members_read** +> TeamMember team_members_read(uuid) + +Retrieve a Team Member + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamMembersApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a Team Member + api_response = api_instance.team_members_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamMembersApi->team_members_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**TeamMember**](TeamMember.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/TeamsApi.md b/docs/TeamsApi.md new file mode 100644 index 0000000..482aed2 --- /dev/null +++ b/docs/TeamsApi.md @@ -0,0 +1,284 @@ +# signrequest_python_client.TeamsApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**teams_create**](TeamsApi.md#teams_create) | **POST** /teams/ | Create a Team +[**teams_invite_member**](TeamsApi.md#teams_invite_member) | **POST** /teams/{subdomain}/invite_member/ | Invite a Team Member +[**teams_list**](TeamsApi.md#teams_list) | **GET** /teams/ | Retrieve a list of Teams +[**teams_partial_update**](TeamsApi.md#teams_partial_update) | **PATCH** /teams/{subdomain}/ | Update a Team +[**teams_read**](TeamsApi.md#teams_read) | **GET** /teams/{subdomain}/ | Retrieve a Team + + +# **teams_create** +> Team teams_create(data) + +Create a Team + +Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.Team() # Team | + +try: + # Create a Team + api_response = api_instance.teams_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamsApi->teams_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**Team**](Team.md)| | + +### Return type + +[**Team**](Team.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **teams_invite_member** +> InviteMember teams_invite_member(subdomain, data) + +Invite a Team Member + +Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +subdomain = 'subdomain_example' # str | +data = signrequest_python_client.InviteMember() # InviteMember | + +try: + # Invite a Team Member + api_response = api_instance.teams_invite_member(subdomain, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamsApi->teams_invite_member: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **subdomain** | **str**| | + **data** | [**InviteMember**](InviteMember.md)| | + +### Return type + +[**InviteMember**](InviteMember.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **teams_list** +> InlineResponse2007 teams_list(page=page, limit=limit) + +Retrieve a list of Teams + +Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Teams + api_response = api_instance.teams_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamsApi->teams_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2007**](InlineResponse2007.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **teams_partial_update** +> Team teams_partial_update(subdomain, data) + +Update a Team + +Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +subdomain = 'subdomain_example' # str | +data = signrequest_python_client.Team() # Team | + +try: + # Update a Team + api_response = api_instance.teams_partial_update(subdomain, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamsApi->teams_partial_update: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **subdomain** | **str**| | + **data** | [**Team**](Team.md)| | + +### Return type + +[**Team**](Team.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **teams_read** +> Team teams_read(subdomain) + +Retrieve a Team + +Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +subdomain = 'subdomain_example' # str | + +try: + # Retrieve a Team + api_response = api_instance.teams_read(subdomain) + pprint(api_response) +except ApiException as e: + print("Exception when calling TeamsApi->teams_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **subdomain** | **str**| | + +### Return type + +[**Team**](Team.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/Template.md b/docs/Template.md new file mode 100644 index 0000000..191c705 --- /dev/null +++ b/docs/Template.md @@ -0,0 +1,15 @@ +# Template + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**url** | **str** | | [optional] +**name** | **str** | Defaults to filename | [optional] +**uuid** | **str** | | [optional] +**user** | [**User**](User.md) | | [optional] +**who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] +**signers** | [**list[DocumentSignerTemplateConf]**](DocumentSignerTemplateConf.md) | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/TemplatesApi.md b/docs/TemplatesApi.md new file mode 100644 index 0000000..04039fd --- /dev/null +++ b/docs/TemplatesApi.md @@ -0,0 +1,118 @@ +# signrequest_python_client.TemplatesApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**templates_list**](TemplatesApi.md#templates_list) | **GET** /templates/ | Retrieve a list of Templates +[**templates_read**](TemplatesApi.md#templates_read) | **GET** /templates/{uuid}/ | Retrieve a Template + + +# **templates_list** +> InlineResponse2008 templates_list(page=page, limit=limit) + +Retrieve a list of Templates + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TemplatesApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Templates + api_response = api_instance.templates_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling TemplatesApi->templates_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2008**](InlineResponse2008.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **templates_read** +> Template templates_read(uuid) + +Retrieve a Template + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.TemplatesApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a Template + api_response = api_instance.templates_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling TemplatesApi->templates_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**Template**](Template.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/docs/User.md b/docs/User.md new file mode 100644 index 0000000..5da0930 --- /dev/null +++ b/docs/User.md @@ -0,0 +1,13 @@ +# User + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**email** | **str** | | +**first_name** | **str** | | [optional] +**last_name** | **str** | | [optional] +**display_name** | **str** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/WebhookSubscription.md b/docs/WebhookSubscription.md new file mode 100644 index 0000000..55fa57f --- /dev/null +++ b/docs/WebhookSubscription.md @@ -0,0 +1,16 @@ +# WebhookSubscription + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**url** | **str** | | [optional] +**uuid** | **str** | | [optional] +**name** | **str** | Optional name to easily identify what webhook is used for | [optional] +**event_type** | **str** | | +**callback_url** | **str** | | +**integration** | **str** | | [optional] +**created** | **datetime** | | [optional] + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/WebhooksApi.md b/docs/WebhooksApi.md new file mode 100644 index 0000000..7ddfe73 --- /dev/null +++ b/docs/WebhooksApi.md @@ -0,0 +1,337 @@ +# signrequest_python_client.WebhooksApi + +All URIs are relative to *https://signrequest.com/api/v1* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**webhooks_create**](WebhooksApi.md#webhooks_create) | **POST** /webhooks/ | Create a Webhook +[**webhooks_delete**](WebhooksApi.md#webhooks_delete) | **DELETE** /webhooks/{uuid}/ | Delete a Webhook +[**webhooks_list**](WebhooksApi.md#webhooks_list) | **GET** /webhooks/ | Retrieve a list of Webhooks +[**webhooks_partial_update**](WebhooksApi.md#webhooks_partial_update) | **PATCH** /webhooks/{uuid}/ | Partially update a Webhook +[**webhooks_read**](WebhooksApi.md#webhooks_read) | **GET** /webhooks/{uuid}/ | Retrieve a Webhook +[**webhooks_update**](WebhooksApi.md#webhooks_update) | **PUT** /webhooks/{uuid}/ | Update a Webhook + + +# **webhooks_create** +> WebhookSubscription webhooks_create(data) + +Create a Webhook + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | + +try: + # Create a Webhook + api_response = api_instance.webhooks_create(data) + pprint(api_response) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_create: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **data** | [**WebhookSubscription**](WebhookSubscription.md)| | + +### Return type + +[**WebhookSubscription**](WebhookSubscription.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **webhooks_delete** +> webhooks_delete(uuid) + +Delete a Webhook + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Delete a Webhook + api_instance.webhooks_delete(uuid) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_delete: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +void (empty response body) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **webhooks_list** +> InlineResponse2009 webhooks_list(page=page, limit=limit) + +Retrieve a list of Webhooks + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +page = 56 # int | A page number within the paginated result set. (optional) +limit = 56 # int | Number of results to return per page. (optional) + +try: + # Retrieve a list of Webhooks + api_response = api_instance.webhooks_list(page=page, limit=limit) + pprint(api_response) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_list: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **page** | **int**| A page number within the paginated result set. | [optional] + **limit** | **int**| Number of results to return per page. | [optional] + +### Return type + +[**InlineResponse2009**](InlineResponse2009.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **webhooks_partial_update** +> WebhookSubscription webhooks_partial_update(uuid, data) + +Partially update a Webhook + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | +data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | + +try: + # Partially update a Webhook + api_response = api_instance.webhooks_partial_update(uuid, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_partial_update: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + **data** | [**WebhookSubscription**](WebhookSubscription.md)| | + +### Return type + +[**WebhookSubscription**](WebhookSubscription.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **webhooks_read** +> WebhookSubscription webhooks_read(uuid) + +Retrieve a Webhook + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | + +try: + # Retrieve a Webhook + api_response = api_instance.webhooks_read(uuid) + pprint(api_response) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_read: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + +### Return type + +[**WebhookSubscription**](WebhookSubscription.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + +# **webhooks_update** +> WebhookSubscription webhooks_update(uuid, data) + +Update a Webhook + + + +### Example +```python +from __future__ import print_function +import time +import signrequest_python_client +from signrequest_python_client.rest import ApiException +from pprint import pprint + +# Configure API key authorization: Token +configuration = signrequest_python_client.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Token' + +# create an instance of the API class +api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +uuid = 'uuid_example' # str | +data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | + +try: + # Update a Webhook + api_response = api_instance.webhooks_update(uuid, data) + pprint(api_response) +except ApiException as e: + print("Exception when calling WebhooksApi->webhooks_update: %s\n" % e) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **uuid** | **str**| | + **data** | [**WebhookSubscription**](WebhookSubscription.md)| | + +### Return type + +[**WebhookSubscription**](WebhookSubscription.md) + +### Authorization + +[Token](../README.md#Token) + +### HTTP request headers + + - **Content-Type**: application/json + - **Accept**: application/json + +[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) + diff --git a/git_push.sh b/git_push.sh new file mode 100644 index 0000000..ae01b18 --- /dev/null +++ b/git_push.sh @@ -0,0 +1,52 @@ +#!/bin/sh +# ref: https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/ +# +# Usage example: /bin/sh ./git_push.sh wing328 swagger-petstore-perl "minor update" + +git_user_id=$1 +git_repo_id=$2 +release_note=$3 + +if [ "$git_user_id" = "" ]; then + git_user_id="GIT_USER_ID" + echo "[INFO] No command line input provided. Set \$git_user_id to $git_user_id" +fi + +if [ "$git_repo_id" = "" ]; then + git_repo_id="GIT_REPO_ID" + echo "[INFO] No command line input provided. Set \$git_repo_id to $git_repo_id" +fi + +if [ "$release_note" = "" ]; then + release_note="Minor update" + echo "[INFO] No command line input provided. Set \$release_note to $release_note" +fi + +# Initialize the local directory as a Git repository +git init + +# Adds the files in the local repository and stages them for commit. +git add . + +# Commits the tracked changes and prepares them to be pushed to a remote repository. +git commit -m "$release_note" + +# Sets the new remote +git_remote=`git remote` +if [ "$git_remote" = "" ]; then # git remote not defined + + if [ "$GIT_TOKEN" = "" ]; then + echo "[INFO] \$GIT_TOKEN (environment variable) is not set. Using the git credential in your environment." + git remote add origin https://github.com/${git_user_id}/${git_repo_id}.git + else + git remote add origin https://${git_user_id}:${GIT_TOKEN}@github.com/${git_user_id}/${git_repo_id}.git + fi + +fi + +git pull origin master + +# Pushes (Forces) the changes in the local repository up to the remote repository +echo "Git pushing to https://github.com/${git_user_id}/${git_repo_id}.git" +git push origin master 2>&1 | grep -v 'To https' + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..bafdc07 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +certifi >= 14.05.14 +six >= 1.10 +python_dateutil >= 2.5.3 +setuptools >= 21.0.0 +urllib3 >= 1.15.1 diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..369112b --- /dev/null +++ b/setup.py @@ -0,0 +1,46 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from setuptools import setup, find_packages # noqa: H301 +import os + +NAME = "signrequest-python-client" +VERSION = "2.0.0" + + +def read(fname): + return open(os.path.join(os.path.dirname(__file__), fname)).read() + + +# To install the library, run the following +# +# python setup.py install +# +# prerequisite: setuptools +# http://pypi.python.org/pypi/setuptools + +REQUIRES = ["urllib3 >= 1.15", "six >= 1.10", "certifi", "python-dateutil"] + +setup( + name=NAME, + version=VERSION, + author="Michaël Krens", + author_email="michael@signrequest.com", + description="A python client to use the SignRequest REST api", + url="https://github.com/SignRequest/signrequest-python-client/", + keywords=["SignRequest", "SignRequest API"], + install_requires=REQUIRES, + packages=find_packages(), + include_package_data=True, + long_description=read("README.md") +) diff --git a/signrequest_python_client/__init__.py b/signrequest_python_client/__init__.py new file mode 100644 index 0000000..7af77b1 --- /dev/null +++ b/signrequest_python_client/__init__.py @@ -0,0 +1,71 @@ +# coding: utf-8 + +# flake8: noqa + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +# import apis into sdk package +from signrequest_python_client.api.api_tokens_api import ApiTokensApi +from signrequest_python_client.api.document_attachments_api import DocumentAttachmentsApi +from signrequest_python_client.api.documents_api import DocumentsApi +from signrequest_python_client.api.documents_search_api import DocumentsSearchApi +from signrequest_python_client.api.events_api import EventsApi +from signrequest_python_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi +from signrequest_python_client.api.signrequests_api import SignrequestsApi +from signrequest_python_client.api.team_members_api import TeamMembersApi +from signrequest_python_client.api.teams_api import TeamsApi +from signrequest_python_client.api.templates_api import TemplatesApi +from signrequest_python_client.api.webhooks_api import WebhooksApi + +# import ApiClient +from signrequest_python_client.api_client import ApiClient +from signrequest_python_client.configuration import Configuration +# import models into sdk package +from signrequest_python_client.models.auth_token import AuthToken +from signrequest_python_client.models.document import Document +from signrequest_python_client.models.document_attachment import DocumentAttachment +from signrequest_python_client.models.document_search import DocumentSearch +from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf +from signrequest_python_client.models.event import Event +from signrequest_python_client.models.file_from_sf import FileFromSf +from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData +from signrequest_python_client.models.inline_integration_data import InlineIntegrationData +from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags +from signrequest_python_client.models.inline_response_200 import InlineResponse200 +from signrequest_python_client.models.inline_response_200_1 import InlineResponse2001 +from signrequest_python_client.models.inline_response_200_2 import InlineResponse2002 +from signrequest_python_client.models.inline_response_200_3 import InlineResponse2003 +from signrequest_python_client.models.inline_response_200_4 import InlineResponse2004 +from signrequest_python_client.models.inline_response_200_5 import InlineResponse2005 +from signrequest_python_client.models.inline_response_200_6 import InlineResponse2006 +from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 +from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 +from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_python_client.models.inline_sign_request import InlineSignRequest +from signrequest_python_client.models.inline_team import InlineTeam +from signrequest_python_client.models.inline_team_member import InlineTeamMember +from signrequest_python_client.models.invite_member import InviteMember +from signrequest_python_client.models.placeholder import Placeholder +from signrequest_python_client.models.required_attachment import RequiredAttachment +from signrequest_python_client.models.sign_request import SignRequest +from signrequest_python_client.models.sign_request_quick_create import SignRequestQuickCreate +from signrequest_python_client.models.signer import Signer +from signrequest_python_client.models.signer_attachment import SignerAttachment +from signrequest_python_client.models.signer_inputs import SignerInputs +from signrequest_python_client.models.signing_log import SigningLog +from signrequest_python_client.models.team import Team +from signrequest_python_client.models.team_member import TeamMember +from signrequest_python_client.models.template import Template +from signrequest_python_client.models.user import User +from signrequest_python_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_python_client/api/__init__.py b/signrequest_python_client/api/__init__.py new file mode 100644 index 0000000..1acff6e --- /dev/null +++ b/signrequest_python_client/api/__init__.py @@ -0,0 +1,16 @@ +from __future__ import absolute_import + +# flake8: noqa + +# import apis into api package +from signrequest_python_client.api.api_tokens_api import ApiTokensApi +from signrequest_python_client.api.document_attachments_api import DocumentAttachmentsApi +from signrequest_python_client.api.documents_api import DocumentsApi +from signrequest_python_client.api.documents_search_api import DocumentsSearchApi +from signrequest_python_client.api.events_api import EventsApi +from signrequest_python_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi +from signrequest_python_client.api.signrequests_api import SignrequestsApi +from signrequest_python_client.api.team_members_api import TeamMembersApi +from signrequest_python_client.api.teams_api import TeamsApi +from signrequest_python_client.api.templates_api import TemplatesApi +from signrequest_python_client.api.webhooks_api import WebhooksApi diff --git a/signrequest_python_client/api/api_tokens_api.py b/signrequest_python_client/api/api_tokens_api.py new file mode 100644 index 0000000..14be6e1 --- /dev/null +++ b/signrequest_python_client/api/api_tokens_api.py @@ -0,0 +1,430 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class ApiTokensApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def api_tokens_create(self, data, **kwargs): # noqa: E501 + """Create an API token # noqa: E501 + + You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param AuthToken data: (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def api_tokens_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create an API token # noqa: E501 + + You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param AuthToken data: (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `api_tokens_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='AuthToken', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_delete(self, key, **kwargs): # noqa: E501 + """Delete an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_delete(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 + return data + + def api_tokens_delete_with_http_info(self, key, **kwargs): # noqa: E501 + """Delete an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_delete_with_http_info(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['key'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'key' is set + if ('key' not in params or + params['key'] is None): + raise ValueError("Missing the required parameter `key` when calling `api_tokens_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'key' in params: + path_params['key'] = params['key'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/{key}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_list(self, **kwargs): # noqa: E501 + """Retrieve a list of API tokens # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse200 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 + return data + + def api_tokens_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of API tokens # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse200 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse200', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_read(self, key, **kwargs): # noqa: E501 + """Retrieve an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_read(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 + return data + + def api_tokens_read_with_http_info(self, key, **kwargs): # noqa: E501 + """Retrieve an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_read_with_http_info(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['key'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'key' is set + if ('key' not in params or + params['key'] is None): + raise ValueError("Missing the required parameter `key` when calling `api_tokens_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'key' in params: + path_params['key'] = params['key'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/{key}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='AuthToken', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/document_attachments_api.py b/signrequest_python_client/api/document_attachments_api.py new file mode 100644 index 0000000..51f987d --- /dev/null +++ b/signrequest_python_client/api/document_attachments_api.py @@ -0,0 +1,331 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class DocumentAttachmentsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def document_attachments_create(self, data, **kwargs): # noqa: E501 + """Create a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param DocumentAttachment data: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def document_attachments_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param DocumentAttachment data: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `document_attachments_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='DocumentAttachment', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def document_attachments_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Document Attachments # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2001 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 + return data + + def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Document Attachments # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2001 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2001', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def document_attachments_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def document_attachments_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `document_attachments_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='DocumentAttachment', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/documents_api.py b/signrequest_python_client/api/documents_api.py new file mode 100644 index 0000000..95508f3 --- /dev/null +++ b/signrequest_python_client/api/documents_api.py @@ -0,0 +1,430 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class DocumentsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def documents_create(self, data, **kwargs): # noqa: E501 + """Create a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param Document data: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.documents_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def documents_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param Document data: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `documents_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Document', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_delete(self, uuid, **kwargs): # noqa: E501 + """Delete a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_delete(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def documents_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Delete a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_delete_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `documents_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/{uuid}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Documents # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2003 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.documents_list_with_http_info(**kwargs) # noqa: E501 + return data + + def documents_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Documents # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2003 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2003', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def documents_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `documents_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Document', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/documents_search_api.py b/signrequest_python_client/api/documents_search_api.py new file mode 100644 index 0000000..86ad8bd --- /dev/null +++ b/signrequest_python_client/api/documents_search_api.py @@ -0,0 +1,133 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class DocumentsSearchApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def documents_search_list(self, **kwargs): # noqa: E501 + """Search documents # noqa: E501 + + Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_search_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2002 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_search_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.documents_search_list_with_http_info(**kwargs) # noqa: E501 + return data + + def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 + """Search documents # noqa: E501 + + Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_search_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2002 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_search_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json', 'text/csv', 'application/vnd.ms-excel']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents-search/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2002', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/events_api.py b/signrequest_python_client/api/events_api.py new file mode 100644 index 0000000..73207f9 --- /dev/null +++ b/signrequest_python_client/api/events_api.py @@ -0,0 +1,284 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class EventsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def events_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Events # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_list(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str document__signrequest__who: + :param str document__signrequest__from_email: + :param str document__status: + :param str document__user__email: + :param str document__user__first_name: + :param str document__user__last_name: + :param str delivered: + :param str delivered_on: + :param str timestamp: + :param str status: + :param str event_type: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2004 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.events_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.events_list_with_http_info(**kwargs) # noqa: E501 + return data + + def events_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Events # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str document__signrequest__who: + :param str document__signrequest__from_email: + :param str document__status: + :param str document__user__email: + :param str document__user__first_name: + :param str document__user__last_name: + :param str delivered: + :param str delivered_on: + :param str timestamp: + :param str status: + :param str event_type: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2004 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['document__uuid', 'document__external_id', 'document__signrequest__who', 'document__signrequest__from_email', 'document__status', 'document__user__email', 'document__user__first_name', 'document__user__last_name', 'delivered', 'delivered_on', 'timestamp', 'status', 'event_type', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method events_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'document__uuid' in params: + query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 + if 'document__external_id' in params: + query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 + if 'document__signrequest__who' in params: + query_params.append(('document__signrequest__who', params['document__signrequest__who'])) # noqa: E501 + if 'document__signrequest__from_email' in params: + query_params.append(('document__signrequest__from_email', params['document__signrequest__from_email'])) # noqa: E501 + if 'document__status' in params: + query_params.append(('document__status', params['document__status'])) # noqa: E501 + if 'document__user__email' in params: + query_params.append(('document__user__email', params['document__user__email'])) # noqa: E501 + if 'document__user__first_name' in params: + query_params.append(('document__user__first_name', params['document__user__first_name'])) # noqa: E501 + if 'document__user__last_name' in params: + query_params.append(('document__user__last_name', params['document__user__last_name'])) # noqa: E501 + if 'delivered' in params: + query_params.append(('delivered', params['delivered'])) # noqa: E501 + if 'delivered_on' in params: + query_params.append(('delivered_on', params['delivered_on'])) # noqa: E501 + if 'timestamp' in params: + query_params.append(('timestamp', params['timestamp'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'event_type' in params: + query_params.append(('event_type', params['event_type'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/events/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2004', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def events_read(self, id, **kwargs): # noqa: E501 + """Retrieve an Event # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_read(id, async=True) + >>> result = thread.get() + + :param async bool + :param int id: A unique integer value identifying this event. (required) + :return: Event + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.events_read_with_http_info(id, **kwargs) # noqa: E501 + else: + (data) = self.events_read_with_http_info(id, **kwargs) # noqa: E501 + return data + + def events_read_with_http_info(self, id, **kwargs): # noqa: E501 + """Retrieve an Event # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_read_with_http_info(id, async=True) + >>> result = thread.get() + + :param async bool + :param int id: A unique integer value identifying this event. (required) + :return: Event + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['id'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method events_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'id' is set + if ('id' not in params or + params['id'] is None): + raise ValueError("Missing the required parameter `id` when calling `events_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'id' in params: + path_params['id'] = params['id'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/events/{id}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Event', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/signrequest_quick_create_api.py b/signrequest_python_client/api/signrequest_quick_create_api.py new file mode 100644 index 0000000..de57a6e --- /dev/null +++ b/signrequest_python_client/api/signrequest_quick_create_api.py @@ -0,0 +1,133 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class SignrequestQuickCreateApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def signrequest_quick_create_create(self, data, **kwargs): # noqa: E501 + """Quick create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequest_quick_create_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequestQuickCreate data: (required) + :return: SignRequestQuickCreate + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def signrequest_quick_create_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Quick create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequest_quick_create_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequestQuickCreate data: (required) + :return: SignRequestQuickCreate + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequest_quick_create_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequest_quick_create_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequest-quick-create/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequestQuickCreate', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/signrequests_api.py b/signrequest_python_client/api/signrequests_api.py new file mode 100644 index 0000000..7ed4d0e --- /dev/null +++ b/signrequest_python_client/api/signrequests_api.py @@ -0,0 +1,545 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class SignrequestsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def signrequests_cancel_signrequest(self, uuid, data, **kwargs): # noqa: E501 + """Cancel a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_cancel_signrequest(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_cancel_signrequest_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_cancel_signrequest_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def signrequests_cancel_signrequest_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Cancel a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_cancel_signrequest_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_cancel_signrequest" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_cancel_signrequest`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequests_cancel_signrequest`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/cancel_signrequest/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_create(self, data, **kwargs): # noqa: E501 + """Create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def signrequests_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequests_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_list(self, **kwargs): # noqa: E501 + """Retrieve a list of SignRequests # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2005 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.signrequests_list_with_http_info(**kwargs) # noqa: E501 + return data + + def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of SignRequests # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2005 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2005', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def signrequests_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_resend_signrequest_email(self, uuid, data, **kwargs): # noqa: E501 + """Resend a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_resend_signrequest_email(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_resend_signrequest_email_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_resend_signrequest_email_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def signrequests_resend_signrequest_email_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Resend a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_resend_signrequest_email_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_resend_signrequest_email" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_resend_signrequest_email`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequests_resend_signrequest_email`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/resend_signrequest_email/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/team_members_api.py b/signrequest_python_client/api/team_members_api.py new file mode 100644 index 0000000..7cd70f0 --- /dev/null +++ b/signrequest_python_client/api/team_members_api.py @@ -0,0 +1,256 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class TeamMembersApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def team_members_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Team Members # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_list(async=True) + >>> result = thread.get() + + :param async bool + :param str is_active: + :param str is_owner: + :param str is_admin: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2006 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.team_members_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.team_members_list_with_http_info(**kwargs) # noqa: E501 + return data + + def team_members_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Team Members # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str is_active: + :param str is_owner: + :param str is_admin: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2006 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['is_active', 'is_owner', 'is_admin', 'user__email', 'user__first_name', 'user__last_name', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method team_members_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'is_active' in params: + query_params.append(('is_active', params['is_active'])) # noqa: E501 + if 'is_owner' in params: + query_params.append(('is_owner', params['is_owner'])) # noqa: E501 + if 'is_admin' in params: + query_params.append(('is_admin', params['is_admin'])) # noqa: E501 + if 'user__email' in params: + query_params.append(('user__email', params['user__email'])) # noqa: E501 + if 'user__first_name' in params: + query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 + if 'user__last_name' in params: + query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/team-members/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2006', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def team_members_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Team Member # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: TeamMember + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def team_members_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Team Member # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: TeamMember + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method team_members_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `team_members_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/team-members/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='TeamMember', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/teams_api.py b/signrequest_python_client/api/teams_api.py new file mode 100644 index 0000000..5f50a27 --- /dev/null +++ b/signrequest_python_client/api/teams_api.py @@ -0,0 +1,545 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class TeamsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def teams_create(self, data, **kwargs): # noqa: E501 + """Create a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.teams_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def teams_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_invite_member(self, subdomain, data, **kwargs): # noqa: E501 + """Invite a Team Member # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_invite_member(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param InviteMember data: (required) + :return: InviteMember + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 + else: + (data) = self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 + return data + + def teams_invite_member_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 + """Invite a Team Member # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_invite_member_with_http_info(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param InviteMember data: (required) + :return: InviteMember + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_invite_member" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_invite_member`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_invite_member`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/invite_member/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InviteMember', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Teams # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2007 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.teams_list_with_http_info(**kwargs) # noqa: E501 + return data + + def teams_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Teams # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2007 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2007', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_partial_update(self, subdomain, data, **kwargs): # noqa: E501 + """Update a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_partial_update(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 + else: + (data) = self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 + return data + + def teams_partial_update_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 + """Update a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_partial_update_with_http_info(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_partial_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_partial_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_partial_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/', 'PATCH', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_read(self, subdomain, **kwargs): # noqa: E501 + """Retrieve a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_read(subdomain, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 + else: + (data) = self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 + return data + + def teams_read_with_http_info(self, subdomain, **kwargs): # noqa: E501 + """Retrieve a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_read_with_http_info(subdomain, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/templates_api.py b/signrequest_python_client/api/templates_api.py new file mode 100644 index 0000000..ab50852 --- /dev/null +++ b/signrequest_python_client/api/templates_api.py @@ -0,0 +1,232 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class TemplatesApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def templates_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Templates # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2008 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.templates_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.templates_list_with_http_info(**kwargs) # noqa: E501 + return data + + def templates_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Templates # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2008 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method templates_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/templates/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2008', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def templates_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Template # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Template + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def templates_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Template # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Template + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method templates_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `templates_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/templates/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Template', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api/webhooks_api.py b/signrequest_python_client/api/webhooks_api.py new file mode 100644 index 0000000..6c088dd --- /dev/null +++ b/signrequest_python_client/api/webhooks_api.py @@ -0,0 +1,644 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_python_client.api_client import ApiClient + + +class WebhooksApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def webhooks_create(self, data, **kwargs): # noqa: E501 + """Create a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def webhooks_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_delete(self, uuid, **kwargs): # noqa: E501 + """Delete a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_delete(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def webhooks_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Delete a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_delete_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Webhooks # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2009 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.webhooks_list_with_http_info(**kwargs) # noqa: E501 + return data + + def webhooks_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Webhooks # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2009 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2009', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_partial_update(self, uuid, data, **kwargs): # noqa: E501 + """Partially update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_partial_update(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def webhooks_partial_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Partially update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_partial_update_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_partial_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_partial_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_partial_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'PATCH', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def webhooks_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_update(self, uuid, data, **kwargs): # noqa: E501 + """Update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_update(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def webhooks_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_update_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'PUT', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_python_client/api_client.py b/signrequest_python_client/api_client.py new file mode 100644 index 0000000..6ad4a6c --- /dev/null +++ b/signrequest_python_client/api_client.py @@ -0,0 +1,621 @@ +# coding: utf-8 +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + +from __future__ import absolute_import + +import datetime +import json +import mimetypes +from multiprocessing.pool import ThreadPool +import os +import re +import tempfile + +# python 2 and python 3 compatibility library +import six +from six.moves.urllib.parse import quote + +from signrequest_python_client.configuration import Configuration +import signrequest_python_client.models +from signrequest_python_client import rest + + +class ApiClient(object): + """Generic API client for Swagger client library builds. + + Swagger generic API client. This client handles the client- + server communication, and is invariant across implementations. Specifics of + the methods and models for each application are generated from the Swagger + templates. + + NOTE: This class is auto generated by the swagger code generator program. + Ref: https://github.com/swagger-api/swagger-codegen + Do not edit the class manually. + + :param configuration: .Configuration object for this client + :param header_name: a header to pass when making calls to the API. + :param header_value: a header value to pass when making calls to + the API. + :param cookie: a cookie to include in the header when making calls + to the API + """ + + PRIMITIVE_TYPES = (float, bool, bytes, six.text_type) + six.integer_types + NATIVE_TYPES_MAPPING = { + 'int': int, + 'long': int if six.PY3 else long, # noqa: F821 + 'float': float, + 'str': str, + 'bool': bool, + 'date': datetime.date, + 'datetime': datetime.datetime, + 'object': object, + } + + def __init__(self, configuration=None, header_name=None, header_value=None, + cookie=None): + if configuration is None: + configuration = Configuration() + self.configuration = configuration + + self.pool = ThreadPool() + self.rest_client = rest.RESTClientObject(configuration) + self.default_headers = {} + if header_name is not None: + self.default_headers[header_name] = header_value + self.cookie = cookie + # Set default User-Agent. + self.user_agent = 'Swagger-Codegen/2.0.0/python' + + def __del__(self): + self.pool.close() + self.pool.join() + + @property + def user_agent(self): + """User agent for this API client""" + return self.default_headers['User-Agent'] + + @user_agent.setter + def user_agent(self, value): + self.default_headers['User-Agent'] = value + + def set_default_header(self, header_name, header_value): + self.default_headers[header_name] = header_value + + def __call_api( + self, resource_path, method, path_params=None, + query_params=None, header_params=None, body=None, post_params=None, + files=None, response_type=None, auth_settings=None, + _return_http_data_only=None, collection_formats=None, + _preload_content=True, _request_timeout=None): + + config = self.configuration + + # header parameters + header_params = header_params or {} + header_params.update(self.default_headers) + if self.cookie: + header_params['Cookie'] = self.cookie + if header_params: + header_params = self.sanitize_for_serialization(header_params) + header_params = dict(self.parameters_to_tuples(header_params, + collection_formats)) + + # path parameters + if path_params: + path_params = self.sanitize_for_serialization(path_params) + path_params = self.parameters_to_tuples(path_params, + collection_formats) + for k, v in path_params: + # specified safe chars, encode everything + resource_path = resource_path.replace( + '{%s}' % k, + quote(str(v), safe=config.safe_chars_for_path_param) + ) + + # query parameters + if query_params: + query_params = self.sanitize_for_serialization(query_params) + query_params = self.parameters_to_tuples(query_params, + collection_formats) + + # post parameters + if post_params or files: + post_params = self.prepare_post_parameters(post_params, files) + post_params = self.sanitize_for_serialization(post_params) + post_params = self.parameters_to_tuples(post_params, + collection_formats) + + # auth setting + self.update_params_for_auth(header_params, query_params, auth_settings) + + # body + if body: + body = self.sanitize_for_serialization(body) + + # request url + url = self.configuration.host + resource_path + + # perform request and return response + response_data = self.request( + method, url, query_params=query_params, headers=header_params, + post_params=post_params, body=body, + _preload_content=_preload_content, + _request_timeout=_request_timeout) + + self.last_response = response_data + + return_data = response_data + if _preload_content: + # deserialize response data + if response_type: + return_data = self.deserialize(response_data, response_type) + else: + return_data = None + + if _return_http_data_only: + return (return_data) + else: + return (return_data, response_data.status, + response_data.getheaders()) + + def sanitize_for_serialization(self, obj): + """Builds a JSON POST object. + + If obj is None, return None. + If obj is str, int, long, float, bool, return directly. + If obj is datetime.datetime, datetime.date + convert to string in iso8601 format. + If obj is list, sanitize each element in the list. + If obj is dict, return the dict. + If obj is swagger model, return the properties dict. + + :param obj: The data to serialize. + :return: The serialized form of data. + """ + if obj is None: + return None + elif isinstance(obj, self.PRIMITIVE_TYPES): + return obj + elif isinstance(obj, list): + return [self.sanitize_for_serialization(sub_obj) + for sub_obj in obj] + elif isinstance(obj, tuple): + return tuple(self.sanitize_for_serialization(sub_obj) + for sub_obj in obj) + elif isinstance(obj, (datetime.datetime, datetime.date)): + return obj.isoformat() + + if isinstance(obj, dict): + obj_dict = obj + else: + # Convert model obj to dict except + # attributes `swagger_types`, `attribute_map` + # and attributes which value is not None. + # Convert attribute name to json key in + # model definition for request. + obj_dict = {obj.attribute_map[attr]: getattr(obj, attr) + for attr, _ in six.iteritems(obj.swagger_types) + if getattr(obj, attr) is not None} + + return {key: self.sanitize_for_serialization(val) + for key, val in six.iteritems(obj_dict)} + + def deserialize(self, response, response_type): + """Deserializes response into an object. + + :param response: RESTResponse object to be deserialized. + :param response_type: class literal for + deserialized object, or string of class name. + + :return: deserialized object. + """ + # handle file downloading + # save response body into a tmp file and return the instance + if response_type == "file": + return self.__deserialize_file(response) + + # fetch data from response object + try: + data = json.loads(response.data) + except ValueError: + data = response.data + + return self.__deserialize(data, response_type) + + def __deserialize(self, data, klass): + """Deserializes dict, list, str into an object. + + :param data: dict, list or str. + :param klass: class literal, or string of class name. + + :return: object. + """ + if data is None: + return None + + if type(klass) == str: + if klass.startswith('list['): + sub_kls = re.match('list\[(.*)\]', klass).group(1) + return [self.__deserialize(sub_data, sub_kls) + for sub_data in data] + + if klass.startswith('dict('): + sub_kls = re.match('dict\(([^,]*), (.*)\)', klass).group(2) + return {k: self.__deserialize(v, sub_kls) + for k, v in six.iteritems(data)} + + # convert str to class + if klass in self.NATIVE_TYPES_MAPPING: + klass = self.NATIVE_TYPES_MAPPING[klass] + else: + klass = getattr(signrequest_python_client.models, klass) + + if klass in self.PRIMITIVE_TYPES: + return self.__deserialize_primitive(data, klass) + elif klass == object: + return self.__deserialize_object(data) + elif klass == datetime.date: + return self.__deserialize_date(data) + elif klass == datetime.datetime: + return self.__deserialize_datatime(data) + else: + return self.__deserialize_model(data, klass) + + def call_api(self, resource_path, method, + path_params=None, query_params=None, header_params=None, + body=None, post_params=None, files=None, + response_type=None, auth_settings=None, async=None, + _return_http_data_only=None, collection_formats=None, + _preload_content=True, _request_timeout=None): + """Makes the HTTP request (synchronous) and returns deserialized data. + + To make an async request, set the async parameter. + + :param resource_path: Path to method endpoint. + :param method: Method to call. + :param path_params: Path parameters in the url. + :param query_params: Query parameters in the url. + :param header_params: Header parameters to be + placed in the request header. + :param body: Request body. + :param post_params dict: Request post form parameters, + for `application/x-www-form-urlencoded`, `multipart/form-data`. + :param auth_settings list: Auth Settings names for the request. + :param response: Response data type. + :param files dict: key -> filename, value -> filepath, + for `multipart/form-data`. + :param async bool: execute request asynchronously + :param _return_http_data_only: response data without head status code + and headers + :param collection_formats: dict of collection formats for path, query, + header, and post parameters. + :param _preload_content: if False, the urllib3.HTTPResponse object will + be returned without reading/decoding response + data. Default is True. + :param _request_timeout: timeout setting for this request. If one + number provided, it will be total request + timeout. It can also be a pair (tuple) of + (connection, read) timeouts. + :return: + If async parameter is True, + the request will be called asynchronously. + The method will return the request thread. + If parameter async is False or missing, + then the method will return the response directly. + """ + if not async: + return self.__call_api(resource_path, method, + path_params, query_params, header_params, + body, post_params, files, + response_type, auth_settings, + _return_http_data_only, collection_formats, + _preload_content, _request_timeout) + else: + thread = self.pool.apply_async(self.__call_api, (resource_path, + method, path_params, query_params, + header_params, body, + post_params, files, + response_type, auth_settings, + _return_http_data_only, + collection_formats, + _preload_content, _request_timeout)) + return thread + + def request(self, method, url, query_params=None, headers=None, + post_params=None, body=None, _preload_content=True, + _request_timeout=None): + """Makes the HTTP request using RESTClient.""" + if method == "GET": + return self.rest_client.GET(url, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + headers=headers) + elif method == "HEAD": + return self.rest_client.HEAD(url, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + headers=headers) + elif method == "OPTIONS": + return self.rest_client.OPTIONS(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "POST": + return self.rest_client.POST(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "PUT": + return self.rest_client.PUT(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "PATCH": + return self.rest_client.PATCH(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "DELETE": + return self.rest_client.DELETE(url, + query_params=query_params, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + else: + raise ValueError( + "http method must be `GET`, `HEAD`, `OPTIONS`," + " `POST`, `PATCH`, `PUT` or `DELETE`." + ) + + def parameters_to_tuples(self, params, collection_formats): + """Get parameters as list of tuples, formatting collections. + + :param params: Parameters as dict or list of two-tuples + :param dict collection_formats: Parameter collection formats + :return: Parameters as list of tuples, collections formatted + """ + new_params = [] + if collection_formats is None: + collection_formats = {} + for k, v in six.iteritems(params) if isinstance(params, dict) else params: # noqa: E501 + if k in collection_formats: + collection_format = collection_formats[k] + if collection_format == 'multi': + new_params.extend((k, value) for value in v) + else: + if collection_format == 'ssv': + delimiter = ' ' + elif collection_format == 'tsv': + delimiter = '\t' + elif collection_format == 'pipes': + delimiter = '|' + else: # csv is the default + delimiter = ',' + new_params.append( + (k, delimiter.join(str(value) for value in v))) + else: + new_params.append((k, v)) + return new_params + + def prepare_post_parameters(self, post_params=None, files=None): + """Builds form parameters. + + :param post_params: Normal form parameters. + :param files: File parameters. + :return: Form parameters with files. + """ + params = [] + + if post_params: + params = post_params + + if files: + for k, v in six.iteritems(files): + if not v: + continue + file_names = v if type(v) is list else [v] + for n in file_names: + with open(n, 'rb') as f: + filename = os.path.basename(f.name) + filedata = f.read() + mimetype = (mimetypes.guess_type(filename)[0] or + 'application/octet-stream') + params.append( + tuple([k, tuple([filename, filedata, mimetype])])) + + return params + + def select_header_accept(self, accepts): + """Returns `Accept` based on an array of accepts provided. + + :param accepts: List of headers. + :return: Accept (e.g. application/json). + """ + if not accepts: + return + + accepts = [x.lower() for x in accepts] + + if 'application/json' in accepts: + return 'application/json' + else: + return ', '.join(accepts) + + def select_header_content_type(self, content_types): + """Returns `Content-Type` based on an array of content_types provided. + + :param content_types: List of content-types. + :return: Content-Type (e.g. application/json). + """ + if not content_types: + return 'application/json' + + content_types = [x.lower() for x in content_types] + + if 'application/json' in content_types or '*/*' in content_types: + return 'application/json' + else: + return content_types[0] + + def update_params_for_auth(self, headers, querys, auth_settings): + """Updates header and query params based on authentication setting. + + :param headers: Header parameters dict to be updated. + :param querys: Query parameters tuple list to be updated. + :param auth_settings: Authentication setting identifiers list. + """ + if not auth_settings: + return + + for auth in auth_settings: + auth_setting = self.configuration.auth_settings().get(auth) + if auth_setting: + if not auth_setting['value']: + continue + elif auth_setting['in'] == 'header': + headers[auth_setting['key']] = auth_setting['value'] + elif auth_setting['in'] == 'query': + querys.append((auth_setting['key'], auth_setting['value'])) + else: + raise ValueError( + 'Authentication token must be in `query` or `header`' + ) + + def __deserialize_file(self, response): + """Deserializes body to file + + Saves response body into a file in a temporary folder, + using the filename from the `Content-Disposition` header if provided. + + :param response: RESTResponse. + :return: file path. + """ + fd, path = tempfile.mkstemp(dir=self.configuration.temp_folder_path) + os.close(fd) + os.remove(path) + + content_disposition = response.getheader("Content-Disposition") + if content_disposition: + filename = re.search(r'filename=[\'"]?([^\'"\s]+)[\'"]?', + content_disposition).group(1) + path = os.path.join(os.path.dirname(path), filename) + + with open(path, "wb") as f: + f.write(response.data) + + return path + + def __deserialize_primitive(self, data, klass): + """Deserializes string to primitive type. + + :param data: str. + :param klass: class literal. + + :return: int, long, float, str, bool. + """ + try: + return klass(data) + except UnicodeEncodeError: + return six.u(data) + except TypeError: + return data + + def __deserialize_object(self, value): + """Return a original value. + + :return: object. + """ + return value + + def __deserialize_date(self, string): + """Deserializes string to date. + + :param string: str. + :return: date. + """ + try: + from dateutil.parser import parse + return parse(string).date() + except ImportError: + return string + except ValueError: + raise rest.ApiException( + status=0, + reason="Failed to parse `{0}` as date object".format(string) + ) + + def __deserialize_datatime(self, string): + """Deserializes string to datetime. + + The string should be in iso8601 datetime format. + + :param string: str. + :return: datetime. + """ + try: + from dateutil.parser import parse + return parse(string) + except ImportError: + return string + except ValueError: + raise rest.ApiException( + status=0, + reason=( + "Failed to parse `{0}` as datetime object" + .format(string) + ) + ) + + def __deserialize_model(self, data, klass): + """Deserializes list or dict to model. + + :param data: dict, list. + :param klass: class literal. + :return: model object. + """ + + if not klass.swagger_types and not hasattr(klass, + 'get_real_child_model'): + return data + + kwargs = {} + if klass.swagger_types is not None: + for attr, attr_type in six.iteritems(klass.swagger_types): + if (data is not None and + klass.attribute_map[attr] in data and + isinstance(data, (list, dict))): + value = data[klass.attribute_map[attr]] + kwargs[attr] = self.__deserialize(value, attr_type) + + instance = klass(**kwargs) + + if hasattr(instance, 'get_real_child_model'): + klass_name = instance.get_real_child_model(data) + if klass_name: + instance = self.__deserialize(data, klass_name) + return instance diff --git a/signrequest_python_client/configuration.py b/signrequest_python_client/configuration.py new file mode 100644 index 0000000..3a11624 --- /dev/null +++ b/signrequest_python_client/configuration.py @@ -0,0 +1,247 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import copy +import logging +import multiprocessing +import sys +import urllib3 + +import six +from six.moves import http_client as httplib + + +class TypeWithDefault(type): + def __init__(cls, name, bases, dct): + super(TypeWithDefault, cls).__init__(name, bases, dct) + cls._default = None + + def __call__(cls): + if cls._default is None: + cls._default = type.__call__(cls) + return copy.copy(cls._default) + + def set_default(cls, default): + cls._default = copy.copy(default) + + +class Configuration(six.with_metaclass(TypeWithDefault, object)): + """NOTE: This class is auto generated by the swagger code generator program. + + Ref: https://github.com/swagger-api/swagger-codegen + Do not edit the class manually. + """ + + def __init__(self): + """Constructor""" + # Default Base url + self.host = "https://signrequest.com/api/v1" + # Temp file folder for downloading files + self.temp_folder_path = None + + # Authentication Settings + # dict to store API key(s) + self.api_key = {} + # dict to store API prefix (e.g. Bearer) + self.api_key_prefix = {} + # Username for HTTP basic authentication + self.username = "" + # Password for HTTP basic authentication + self.password = "" + + # Logging Settings + self.logger = {} + self.logger["package_logger"] = logging.getLogger("signrequest_python_client") + self.logger["urllib3_logger"] = logging.getLogger("urllib3") + # Log format + self.logger_format = '%(asctime)s %(levelname)s %(message)s' + # Log stream handler + self.logger_stream_handler = None + # Log file handler + self.logger_file_handler = None + # Debug file location + self.logger_file = None + # Debug switch + self.debug = False + + # SSL/TLS verification + # Set this to false to skip verifying SSL certificate when calling API + # from https server. + self.verify_ssl = True + # Set this to customize the certificate file to verify the peer. + self.ssl_ca_cert = None + # client certificate file + self.cert_file = None + # client key file + self.key_file = None + # Set this to True/False to enable/disable SSL hostname verification. + self.assert_hostname = None + + # urllib3 connection pool's maximum number of connections saved + # per pool. urllib3 uses 1 connection as default value, but this is + # not the best value when you are making a lot of possibly parallel + # requests to the same host, which is often the case here. + # cpu_count * 5 is used as default value to increase performance. + self.connection_pool_maxsize = multiprocessing.cpu_count() * 5 + + # Proxy URL + self.proxy = None + # Safe chars for path_param + self.safe_chars_for_path_param = '' + + @property + def logger_file(self): + """The logger file. + + If the logger_file is None, then add stream handler and remove file + handler. Otherwise, add file handler and remove stream handler. + + :param value: The logger_file path. + :type: str + """ + return self.__logger_file + + @logger_file.setter + def logger_file(self, value): + """The logger file. + + If the logger_file is None, then add stream handler and remove file + handler. Otherwise, add file handler and remove stream handler. + + :param value: The logger_file path. + :type: str + """ + self.__logger_file = value + if self.__logger_file: + # If set logging file, + # then add file handler and remove stream handler. + self.logger_file_handler = logging.FileHandler(self.__logger_file) + self.logger_file_handler.setFormatter(self.logger_formatter) + for _, logger in six.iteritems(self.logger): + logger.addHandler(self.logger_file_handler) + if self.logger_stream_handler: + logger.removeHandler(self.logger_stream_handler) + else: + # If not set logging file, + # then add stream handler and remove file handler. + self.logger_stream_handler = logging.StreamHandler() + self.logger_stream_handler.setFormatter(self.logger_formatter) + for _, logger in six.iteritems(self.logger): + logger.addHandler(self.logger_stream_handler) + if self.logger_file_handler: + logger.removeHandler(self.logger_file_handler) + + @property + def debug(self): + """Debug status + + :param value: The debug status, True or False. + :type: bool + """ + return self.__debug + + @debug.setter + def debug(self, value): + """Debug status + + :param value: The debug status, True or False. + :type: bool + """ + self.__debug = value + if self.__debug: + # if debug status is True, turn on debug logging + for _, logger in six.iteritems(self.logger): + logger.setLevel(logging.DEBUG) + # turn on httplib debug + httplib.HTTPConnection.debuglevel = 1 + else: + # if debug status is False, turn off debug logging, + # setting log level to default `logging.WARNING` + for _, logger in six.iteritems(self.logger): + logger.setLevel(logging.WARNING) + # turn off httplib debug + httplib.HTTPConnection.debuglevel = 0 + + @property + def logger_format(self): + """The logger format. + + The logger_formatter will be updated when sets logger_format. + + :param value: The format string. + :type: str + """ + return self.__logger_format + + @logger_format.setter + def logger_format(self, value): + """The logger format. + + The logger_formatter will be updated when sets logger_format. + + :param value: The format string. + :type: str + """ + self.__logger_format = value + self.logger_formatter = logging.Formatter(self.__logger_format) + + def get_api_key_with_prefix(self, identifier): + """Gets API key (with prefix if set). + + :param identifier: The identifier of apiKey. + :return: The token for api key authentication. + """ + if (self.api_key.get(identifier) and + self.api_key_prefix.get(identifier)): + return self.api_key_prefix[identifier] + ' ' + self.api_key[identifier] # noqa: E501 + elif self.api_key.get(identifier): + return self.api_key[identifier] + + def get_basic_auth_token(self): + """Gets HTTP basic authentication header (string). + + :return: The token for basic HTTP authentication. + """ + return urllib3.util.make_headers( + basic_auth=self.username + ':' + self.password + ).get('authorization') + + def auth_settings(self): + """Gets Auth Settings dict for api client. + + :return: The Auth Settings information dict. + """ + return { + 'Token': + { + 'type': 'api_key', + 'in': 'header', + 'key': 'Authorization', + 'value': self.get_api_key_with_prefix('Authorization') + }, + + } + + def to_debug_report(self): + """Gets the essential information for debugging. + + :return: The report for debugging. + """ + return "Python SDK Debug Report:\n"\ + "OS: {env}\n"\ + "Python Version: {pyversion}\n"\ + "Version of the API: v1\n"\ + "SDK Package Version: 2.0.0".\ + format(env=sys.platform, pyversion=sys.version) diff --git a/signrequest_python_client/models/__init__.py b/signrequest_python_client/models/__init__.py new file mode 100644 index 0000000..f3731e2 --- /dev/null +++ b/signrequest_python_client/models/__init__.py @@ -0,0 +1,54 @@ +# coding: utf-8 + +# flake8: noqa +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +# import models into model package +from signrequest_python_client.models.auth_token import AuthToken +from signrequest_python_client.models.document import Document +from signrequest_python_client.models.document_attachment import DocumentAttachment +from signrequest_python_client.models.document_search import DocumentSearch +from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf +from signrequest_python_client.models.event import Event +from signrequest_python_client.models.file_from_sf import FileFromSf +from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData +from signrequest_python_client.models.inline_integration_data import InlineIntegrationData +from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags +from signrequest_python_client.models.inline_response_200 import InlineResponse200 +from signrequest_python_client.models.inline_response_200_1 import InlineResponse2001 +from signrequest_python_client.models.inline_response_200_2 import InlineResponse2002 +from signrequest_python_client.models.inline_response_200_3 import InlineResponse2003 +from signrequest_python_client.models.inline_response_200_4 import InlineResponse2004 +from signrequest_python_client.models.inline_response_200_5 import InlineResponse2005 +from signrequest_python_client.models.inline_response_200_6 import InlineResponse2006 +from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 +from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 +from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_python_client.models.inline_sign_request import InlineSignRequest +from signrequest_python_client.models.inline_team import InlineTeam +from signrequest_python_client.models.inline_team_member import InlineTeamMember +from signrequest_python_client.models.invite_member import InviteMember +from signrequest_python_client.models.placeholder import Placeholder +from signrequest_python_client.models.required_attachment import RequiredAttachment +from signrequest_python_client.models.sign_request import SignRequest +from signrequest_python_client.models.sign_request_quick_create import SignRequestQuickCreate +from signrequest_python_client.models.signer import Signer +from signrequest_python_client.models.signer_attachment import SignerAttachment +from signrequest_python_client.models.signer_inputs import SignerInputs +from signrequest_python_client.models.signing_log import SigningLog +from signrequest_python_client.models.team import Team +from signrequest_python_client.models.team_member import TeamMember +from signrequest_python_client.models.template import Template +from signrequest_python_client.models.user import User +from signrequest_python_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_python_client/models/auth_token.py b/signrequest_python_client/models/auth_token.py new file mode 100644 index 0000000..5378f52 --- /dev/null +++ b/signrequest_python_client/models/auth_token.py @@ -0,0 +1,251 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class AuthToken(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'password': 'str', + 'subdomain': 'str', + 'name': 'str', + 'key': 'str', + 'url': 'str' + } + + attribute_map = { + 'email': 'email', + 'password': 'password', + 'subdomain': 'subdomain', + 'name': 'name', + 'key': 'key', + 'url': 'url' + } + + def __init__(self, email=None, password=None, subdomain=None, name=None, key=None, url=None): # noqa: E501 + """AuthToken - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._password = None + self._subdomain = None + self._name = None + self._key = None + self._url = None + self.discriminator = None + + if email is not None: + self.email = email + if password is not None: + self.password = password + self.subdomain = subdomain + if name is not None: + self.name = name + if key is not None: + self.key = key + if url is not None: + self.url = url + + @property + def email(self): + """Gets the email of this AuthToken. # noqa: E501 + + + :return: The email of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this AuthToken. + + + :param email: The email of this AuthToken. # noqa: E501 + :type: str + """ + + self._email = email + + @property + def password(self): + """Gets the password of this AuthToken. # noqa: E501 + + + :return: The password of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._password + + @password.setter + def password(self, password): + """Sets the password of this AuthToken. + + + :param password: The password of this AuthToken. # noqa: E501 + :type: str + """ + + self._password = password + + @property + def subdomain(self): + """Gets the subdomain of this AuthToken. # noqa: E501 + + + :return: The subdomain of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this AuthToken. + + + :param subdomain: The subdomain of this AuthToken. # noqa: E501 + :type: str + """ + if subdomain is None: + raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 + raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 + + self._subdomain = subdomain + + @property + def name(self): + """Gets the name of this AuthToken. # noqa: E501 + + + :return: The name of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this AuthToken. + + + :param name: The name of this AuthToken. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def key(self): + """Gets the key of this AuthToken. # noqa: E501 + + + :return: The key of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._key + + @key.setter + def key(self, key): + """Sets the key of this AuthToken. + + + :param key: The key of this AuthToken. # noqa: E501 + :type: str + """ + if key is not None and len(key) < 1: + raise ValueError("Invalid value for `key`, length must be greater than or equal to `1`") # noqa: E501 + + self._key = key + + @property + def url(self): + """Gets the url of this AuthToken. # noqa: E501 + + + :return: The url of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this AuthToken. + + + :param url: The url of this AuthToken. # noqa: E501 + :type: str + """ + + self._url = url + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, AuthToken): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/document.py b/signrequest_python_client/models/document.py new file mode 100644 index 0000000..abad23e --- /dev/null +++ b/signrequest_python_client/models/document.py @@ -0,0 +1,775 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 +from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: F401,E501 +from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 +from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 +from signrequest_python_client.models.inline_sign_request import InlineSignRequest # noqa: F401,E501 +from signrequest_python_client.models.user import User # noqa: F401,E501 + + +class Document(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'user': 'User', + 'file_as_pdf': 'str', + 'name': 'str', + 'external_id': 'str', + 'frontend_id': 'str', + 'file': 'str', + 'file_from_url': 'str', + 'events_callback_url': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'template': 'str', + 'prefill_tags': 'list[InlinePrefillTags]', + 'integrations': 'list[InlineIntegrationData]', + 'file_from_sf': 'FileFromSf', + 'auto_delete_days': 'int', + 'pdf': 'str', + 'status': 'str', + 'signrequest': 'InlineSignRequest', + 'api_used': 'bool', + 'security_hash': 'str', + 'attachments': 'list[DocumentAttachment]', + 'auto_delete_after': 'datetime' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'user': 'user', + 'file_as_pdf': 'file_as_pdf', + 'name': 'name', + 'external_id': 'external_id', + 'frontend_id': 'frontend_id', + 'file': 'file', + 'file_from_url': 'file_from_url', + 'events_callback_url': 'events_callback_url', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'template': 'template', + 'prefill_tags': 'prefill_tags', + 'integrations': 'integrations', + 'file_from_sf': 'file_from_sf', + 'auto_delete_days': 'auto_delete_days', + 'pdf': 'pdf', + 'status': 'status', + 'signrequest': 'signrequest', + 'api_used': 'api_used', + 'security_hash': 'security_hash', + 'attachments': 'attachments', + 'auto_delete_after': 'auto_delete_after' + } + + def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None, pdf=None, status=None, signrequest=None, api_used=None, security_hash=None, attachments=None, auto_delete_after=None): # noqa: E501 + """Document - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._user = None + self._file_as_pdf = None + self._name = None + self._external_id = None + self._frontend_id = None + self._file = None + self._file_from_url = None + self._events_callback_url = None + self._file_from_content = None + self._file_from_content_name = None + self._template = None + self._prefill_tags = None + self._integrations = None + self._file_from_sf = None + self._auto_delete_days = None + self._pdf = None + self._status = None + self._signrequest = None + self._api_used = None + self._security_hash = None + self._attachments = None + self._auto_delete_after = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if user is not None: + self.user = user + if file_as_pdf is not None: + self.file_as_pdf = file_as_pdf + if name is not None: + self.name = name + if external_id is not None: + self.external_id = external_id + if frontend_id is not None: + self.frontend_id = frontend_id + if file is not None: + self.file = file + if file_from_url is not None: + self.file_from_url = file_from_url + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if template is not None: + self.template = template + if prefill_tags is not None: + self.prefill_tags = prefill_tags + if integrations is not None: + self.integrations = integrations + if file_from_sf is not None: + self.file_from_sf = file_from_sf + if auto_delete_days is not None: + self.auto_delete_days = auto_delete_days + if pdf is not None: + self.pdf = pdf + if status is not None: + self.status = status + if signrequest is not None: + self.signrequest = signrequest + if api_used is not None: + self.api_used = api_used + if security_hash is not None: + self.security_hash = security_hash + if attachments is not None: + self.attachments = attachments + if auto_delete_after is not None: + self.auto_delete_after = auto_delete_after + + @property + def url(self): + """Gets the url of this Document. # noqa: E501 + + + :return: The url of this Document. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Document. + + + :param url: The url of this Document. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this Document. # noqa: E501 + + + :return: The uuid of this Document. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Document. + + + :param uuid: The uuid of this Document. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def user(self): + """Gets the user of this Document. # noqa: E501 + + + :return: The user of this Document. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this Document. + + + :param user: The user of this Document. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def file_as_pdf(self): + """Gets the file_as_pdf of this Document. # noqa: E501 + + Temporary URL to original file as PDF, expires in five minutes # noqa: E501 + + :return: The file_as_pdf of this Document. # noqa: E501 + :rtype: str + """ + return self._file_as_pdf + + @file_as_pdf.setter + def file_as_pdf(self, file_as_pdf): + """Sets the file_as_pdf of this Document. + + Temporary URL to original file as PDF, expires in five minutes # noqa: E501 + + :param file_as_pdf: The file_as_pdf of this Document. # noqa: E501 + :type: str + """ + if file_as_pdf is not None and len(file_as_pdf) < 1: + raise ValueError("Invalid value for `file_as_pdf`, length must be greater than or equal to `1`") # noqa: E501 + + self._file_as_pdf = file_as_pdf + + @property + def name(self): + """Gets the name of this Document. # noqa: E501 + + Defaults to filename, including extension # noqa: E501 + + :return: The name of this Document. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Document. + + Defaults to filename, including extension # noqa: E501 + + :param name: The name of this Document. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def external_id(self): + """Gets the external_id of this Document. # noqa: E501 + + ID used to reference document in external system # noqa: E501 + + :return: The external_id of this Document. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this Document. + + ID used to reference document in external system # noqa: E501 + + :param external_id: The external_id of this Document. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def frontend_id(self): + """Gets the frontend_id of this Document. # noqa: E501 + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :return: The frontend_id of this Document. # noqa: E501 + :rtype: str + """ + return self._frontend_id + + @frontend_id.setter + def frontend_id(self, frontend_id): + """Sets the frontend_id of this Document. + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :param frontend_id: The frontend_id of this Document. # noqa: E501 + :type: str + """ + if frontend_id is not None and len(frontend_id) > 255: + raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 + + self._frontend_id = frontend_id + + @property + def file(self): + """Gets the file of this Document. # noqa: E501 + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :return: The file of this Document. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this Document. + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :param file: The file of this Document. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_url(self): + """Gets the file_from_url of this Document. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this Document. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this Document. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def events_callback_url(self): + """Gets the events_callback_url of this Document. # noqa: E501 + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :return: The events_callback_url of this Document. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this Document. + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :param events_callback_url: The events_callback_url of this Document. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def file_from_content(self): + """Gets the file_from_content of this Document. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this Document. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this Document. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this Document. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this Document. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this Document. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def template(self): + """Gets the template of this Document. # noqa: E501 + + + :return: The template of this Document. # noqa: E501 + :rtype: str + """ + return self._template + + @template.setter + def template(self, template): + """Sets the template of this Document. + + + :param template: The template of this Document. # noqa: E501 + :type: str + """ + + self._template = template + + @property + def prefill_tags(self): + """Gets the prefill_tags of this Document. # noqa: E501 + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :return: The prefill_tags of this Document. # noqa: E501 + :rtype: list[InlinePrefillTags] + """ + return self._prefill_tags + + @prefill_tags.setter + def prefill_tags(self, prefill_tags): + """Sets the prefill_tags of this Document. + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :param prefill_tags: The prefill_tags of this Document. # noqa: E501 + :type: list[InlinePrefillTags] + """ + + self._prefill_tags = prefill_tags + + @property + def integrations(self): + """Gets the integrations of this Document. # noqa: E501 + + + :return: The integrations of this Document. # noqa: E501 + :rtype: list[InlineIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this Document. + + + :param integrations: The integrations of this Document. # noqa: E501 + :type: list[InlineIntegrationData] + """ + + self._integrations = integrations + + @property + def file_from_sf(self): + """Gets the file_from_sf of this Document. # noqa: E501 + + + :return: The file_from_sf of this Document. # noqa: E501 + :rtype: FileFromSf + """ + return self._file_from_sf + + @file_from_sf.setter + def file_from_sf(self, file_from_sf): + """Sets the file_from_sf of this Document. + + + :param file_from_sf: The file_from_sf of this Document. # noqa: E501 + :type: FileFromSf + """ + + self._file_from_sf = file_from_sf + + @property + def auto_delete_days(self): + """Gets the auto_delete_days of this Document. # noqa: E501 + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_days of this Document. # noqa: E501 + :rtype: int + """ + return self._auto_delete_days + + @auto_delete_days.setter + def auto_delete_days(self, auto_delete_days): + """Sets the auto_delete_days of this Document. + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_days: The auto_delete_days of this Document. # noqa: E501 + :type: int + """ + if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 + if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 + + self._auto_delete_days = auto_delete_days + + @property + def pdf(self): + """Gets the pdf of this Document. # noqa: E501 + + Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 + + :return: The pdf of this Document. # noqa: E501 + :rtype: str + """ + return self._pdf + + @pdf.setter + def pdf(self, pdf): + """Sets the pdf of this Document. + + Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 + + :param pdf: The pdf of this Document. # noqa: E501 + :type: str + """ + + self._pdf = pdf + + @property + def status(self): + """Gets the status of this Document. # noqa: E501 + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + + :return: The status of this Document. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this Document. + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + + :param status: The status of this Document. # noqa: E501 + :type: str + """ + allowed_values = ["co", "ne", "se", "vi", "si", "do", "sd", "ca", "de", "ec", "es"] # noqa: E501 + if status not in allowed_values: + raise ValueError( + "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 + .format(status, allowed_values) + ) + + self._status = status + + @property + def signrequest(self): + """Gets the signrequest of this Document. # noqa: E501 + + + :return: The signrequest of this Document. # noqa: E501 + :rtype: InlineSignRequest + """ + return self._signrequest + + @signrequest.setter + def signrequest(self, signrequest): + """Sets the signrequest of this Document. + + + :param signrequest: The signrequest of this Document. # noqa: E501 + :type: InlineSignRequest + """ + + self._signrequest = signrequest + + @property + def api_used(self): + """Gets the api_used of this Document. # noqa: E501 + + Indicates whether document was created using the API # noqa: E501 + + :return: The api_used of this Document. # noqa: E501 + :rtype: bool + """ + return self._api_used + + @api_used.setter + def api_used(self, api_used): + """Sets the api_used of this Document. + + Indicates whether document was created using the API # noqa: E501 + + :param api_used: The api_used of this Document. # noqa: E501 + :type: bool + """ + + self._api_used = api_used + + @property + def security_hash(self): + """Gets the security_hash of this Document. # noqa: E501 + + SHA256 hash of PDF contents # noqa: E501 + + :return: The security_hash of this Document. # noqa: E501 + :rtype: str + """ + return self._security_hash + + @security_hash.setter + def security_hash(self, security_hash): + """Sets the security_hash of this Document. + + SHA256 hash of PDF contents # noqa: E501 + + :param security_hash: The security_hash of this Document. # noqa: E501 + :type: str + """ + if security_hash is not None and len(security_hash) < 1: + raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 + + self._security_hash = security_hash + + @property + def attachments(self): + """Gets the attachments of this Document. # noqa: E501 + + + :return: The attachments of this Document. # noqa: E501 + :rtype: list[DocumentAttachment] + """ + return self._attachments + + @attachments.setter + def attachments(self, attachments): + """Sets the attachments of this Document. + + + :param attachments: The attachments of this Document. # noqa: E501 + :type: list[DocumentAttachment] + """ + + self._attachments = attachments + + @property + def auto_delete_after(self): + """Gets the auto_delete_after of this Document. # noqa: E501 + + Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_after of this Document. # noqa: E501 + :rtype: datetime + """ + return self._auto_delete_after + + @auto_delete_after.setter + def auto_delete_after(self, auto_delete_after): + """Sets the auto_delete_after of this Document. + + Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_after: The auto_delete_after of this Document. # noqa: E501 + :type: datetime + """ + + self._auto_delete_after = auto_delete_after + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Document): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/document_attachment.py b/signrequest_python_client/models/document_attachment.py new file mode 100644 index 0000000..198b560 --- /dev/null +++ b/signrequest_python_client/models/document_attachment.py @@ -0,0 +1,311 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class DocumentAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'name': 'str', + 'file': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'file_from_url': 'str', + 'document': 'str' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'name': 'name', + 'file': 'file', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'file_from_url': 'file_from_url', + 'document': 'document' + } + + def __init__(self, url=None, uuid=None, name=None, file=None, file_from_content=None, file_from_content_name=None, file_from_url=None, document=None): # noqa: E501 + """DocumentAttachment - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._name = None + self._file = None + self._file_from_content = None + self._file_from_content_name = None + self._file_from_url = None + self._document = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + if file is not None: + self.file = file + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if file_from_url is not None: + self.file_from_url = file_from_url + self.document = document + + @property + def url(self): + """Gets the url of this DocumentAttachment. # noqa: E501 + + + :return: The url of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this DocumentAttachment. + + + :param url: The url of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this DocumentAttachment. # noqa: E501 + + + :return: The uuid of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this DocumentAttachment. + + + :param uuid: The uuid of this DocumentAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this DocumentAttachment. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this DocumentAttachment. + + Defaults to filename # noqa: E501 + + :param name: The name of this DocumentAttachment. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def file(self): + """Gets the file of this DocumentAttachment. # noqa: E501 + + Temporary URL to document attachment, expires in five minutes # noqa: E501 + + :return: The file of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this DocumentAttachment. + + Temporary URL to document attachment, expires in five minutes # noqa: E501 + + :param file: The file of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_content(self): + """Gets the file_from_content of this DocumentAttachment. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this DocumentAttachment. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this DocumentAttachment. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this DocumentAttachment. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def file_from_url(self): + """Gets the file_from_url of this DocumentAttachment. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this DocumentAttachment. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this DocumentAttachment. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def document(self): + """Gets the document of this DocumentAttachment. # noqa: E501 + + + :return: The document of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this DocumentAttachment. + + + :param document: The document of this DocumentAttachment. # noqa: E501 + :type: str + """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 + + self._document = document + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py new file mode 100644 index 0000000..3edec13 --- /dev/null +++ b/signrequest_python_client/models/document_search.py @@ -0,0 +1,507 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class DocumentSearch(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'status': 'str', + 'name': 'str', + 'who': 'str', + 'nr_extra_docs': 'int', + 'from_email': 'str', + 'parent_doc': 'str', + 'uuid': 'str', + 'created': 'datetime', + 'autocomplete': 'str', + 'finished_on': 'datetime', + 'subdomain': 'str', + 'signer_emails': 'list[str]', + 'status_display': 'str', + 'created_timestamp': 'int', + 'finished_on_timestamp': 'int' + } + + attribute_map = { + 'status': 'status', + 'name': 'name', + 'who': 'who', + 'nr_extra_docs': 'nr_extra_docs', + 'from_email': 'from_email', + 'parent_doc': 'parent_doc', + 'uuid': 'uuid', + 'created': 'created', + 'autocomplete': 'autocomplete', + 'finished_on': 'finished_on', + 'subdomain': 'subdomain', + 'signer_emails': 'signer_emails', + 'status_display': 'status_display', + 'created_timestamp': 'created_timestamp', + 'finished_on_timestamp': 'finished_on_timestamp' + } + + def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, parent_doc=None, uuid=None, created=None, autocomplete=None, finished_on=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None): # noqa: E501 + """DocumentSearch - a model defined in Swagger""" # noqa: E501 + + self._status = None + self._name = None + self._who = None + self._nr_extra_docs = None + self._from_email = None + self._parent_doc = None + self._uuid = None + self._created = None + self._autocomplete = None + self._finished_on = None + self._subdomain = None + self._signer_emails = None + self._status_display = None + self._created_timestamp = None + self._finished_on_timestamp = None + self.discriminator = None + + if status is not None: + self.status = status + if name is not None: + self.name = name + self.who = who + self.nr_extra_docs = nr_extra_docs + self.from_email = from_email + self.parent_doc = parent_doc + if uuid is not None: + self.uuid = uuid + if created is not None: + self.created = created + self.autocomplete = autocomplete + self.finished_on = finished_on + self.subdomain = subdomain + if signer_emails is not None: + self.signer_emails = signer_emails + if status_display is not None: + self.status_display = status_display + if created_timestamp is not None: + self.created_timestamp = created_timestamp + if finished_on_timestamp is not None: + self.finished_on_timestamp = finished_on_timestamp + + @property + def status(self): + """Gets the status of this DocumentSearch. # noqa: E501 + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + + :return: The status of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this DocumentSearch. + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + + :param status: The status of this DocumentSearch. # noqa: E501 + :type: str + """ + if status is not None and len(status) > 2: + raise ValueError("Invalid value for `status`, length must be less than or equal to `2`") # noqa: E501 + if status is not None and len(status) < 1: + raise ValueError("Invalid value for `status`, length must be greater than or equal to `1`") # noqa: E501 + + self._status = status + + @property + def name(self): + """Gets the name of this DocumentSearch. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this DocumentSearch. + + Defaults to filename # noqa: E501 + + :param name: The name of this DocumentSearch. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def who(self): + """Gets the who of this DocumentSearch. # noqa: E501 + + + :return: The who of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this DocumentSearch. + + + :param who: The who of this DocumentSearch. # noqa: E501 + :type: str + """ + if who is None: + raise ValueError("Invalid value for `who`, must not be `None`") # noqa: E501 + if who is not None and len(who) < 1: + raise ValueError("Invalid value for `who`, length must be greater than or equal to `1`") # noqa: E501 + + self._who = who + + @property + def nr_extra_docs(self): + """Gets the nr_extra_docs of this DocumentSearch. # noqa: E501 + + + :return: The nr_extra_docs of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._nr_extra_docs + + @nr_extra_docs.setter + def nr_extra_docs(self, nr_extra_docs): + """Sets the nr_extra_docs of this DocumentSearch. + + + :param nr_extra_docs: The nr_extra_docs of this DocumentSearch. # noqa: E501 + :type: int + """ + if nr_extra_docs is None: + raise ValueError("Invalid value for `nr_extra_docs`, must not be `None`") # noqa: E501 + + self._nr_extra_docs = nr_extra_docs + + @property + def from_email(self): + """Gets the from_email of this DocumentSearch. # noqa: E501 + + + :return: The from_email of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this DocumentSearch. + + + :param from_email: The from_email of this DocumentSearch. # noqa: E501 + :type: str + """ + if from_email is None: + raise ValueError("Invalid value for `from_email`, must not be `None`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def parent_doc(self): + """Gets the parent_doc of this DocumentSearch. # noqa: E501 + + + :return: The parent_doc of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._parent_doc + + @parent_doc.setter + def parent_doc(self, parent_doc): + """Sets the parent_doc of this DocumentSearch. + + + :param parent_doc: The parent_doc of this DocumentSearch. # noqa: E501 + :type: str + """ + if parent_doc is None: + raise ValueError("Invalid value for `parent_doc`, must not be `None`") # noqa: E501 + if parent_doc is not None and len(parent_doc) < 1: + raise ValueError("Invalid value for `parent_doc`, length must be greater than or equal to `1`") # noqa: E501 + + self._parent_doc = parent_doc + + @property + def uuid(self): + """Gets the uuid of this DocumentSearch. # noqa: E501 + + + :return: The uuid of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this DocumentSearch. + + + :param uuid: The uuid of this DocumentSearch. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def created(self): + """Gets the created of this DocumentSearch. # noqa: E501 + + + :return: The created of this DocumentSearch. # noqa: E501 + :rtype: datetime + """ + return self._created + + @created.setter + def created(self, created): + """Sets the created of this DocumentSearch. + + + :param created: The created of this DocumentSearch. # noqa: E501 + :type: datetime + """ + + self._created = created + + @property + def autocomplete(self): + """Gets the autocomplete of this DocumentSearch. # noqa: E501 + + + :return: The autocomplete of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._autocomplete + + @autocomplete.setter + def autocomplete(self, autocomplete): + """Sets the autocomplete of this DocumentSearch. + + + :param autocomplete: The autocomplete of this DocumentSearch. # noqa: E501 + :type: str + """ + if autocomplete is None: + raise ValueError("Invalid value for `autocomplete`, must not be `None`") # noqa: E501 + if autocomplete is not None and len(autocomplete) < 1: + raise ValueError("Invalid value for `autocomplete`, length must be greater than or equal to `1`") # noqa: E501 + + self._autocomplete = autocomplete + + @property + def finished_on(self): + """Gets the finished_on of this DocumentSearch. # noqa: E501 + + + :return: The finished_on of this DocumentSearch. # noqa: E501 + :rtype: datetime + """ + return self._finished_on + + @finished_on.setter + def finished_on(self, finished_on): + """Sets the finished_on of this DocumentSearch. + + + :param finished_on: The finished_on of this DocumentSearch. # noqa: E501 + :type: datetime + """ + if finished_on is None: + raise ValueError("Invalid value for `finished_on`, must not be `None`") # noqa: E501 + + self._finished_on = finished_on + + @property + def subdomain(self): + """Gets the subdomain of this DocumentSearch. # noqa: E501 + + + :return: The subdomain of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this DocumentSearch. + + + :param subdomain: The subdomain of this DocumentSearch. # noqa: E501 + :type: str + """ + if subdomain is None: + raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + + self._subdomain = subdomain + + @property + def signer_emails(self): + """Gets the signer_emails of this DocumentSearch. # noqa: E501 + + + :return: The signer_emails of this DocumentSearch. # noqa: E501 + :rtype: list[str] + """ + return self._signer_emails + + @signer_emails.setter + def signer_emails(self, signer_emails): + """Sets the signer_emails of this DocumentSearch. + + + :param signer_emails: The signer_emails of this DocumentSearch. # noqa: E501 + :type: list[str] + """ + + self._signer_emails = signer_emails + + @property + def status_display(self): + """Gets the status_display of this DocumentSearch. # noqa: E501 + + + :return: The status_display of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._status_display + + @status_display.setter + def status_display(self, status_display): + """Sets the status_display of this DocumentSearch. + + + :param status_display: The status_display of this DocumentSearch. # noqa: E501 + :type: str + """ + if status_display is not None and len(status_display) < 1: + raise ValueError("Invalid value for `status_display`, length must be greater than or equal to `1`") # noqa: E501 + + self._status_display = status_display + + @property + def created_timestamp(self): + """Gets the created_timestamp of this DocumentSearch. # noqa: E501 + + + :return: The created_timestamp of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._created_timestamp + + @created_timestamp.setter + def created_timestamp(self, created_timestamp): + """Sets the created_timestamp of this DocumentSearch. + + + :param created_timestamp: The created_timestamp of this DocumentSearch. # noqa: E501 + :type: int + """ + + self._created_timestamp = created_timestamp + + @property + def finished_on_timestamp(self): + """Gets the finished_on_timestamp of this DocumentSearch. # noqa: E501 + + + :return: The finished_on_timestamp of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._finished_on_timestamp + + @finished_on_timestamp.setter + def finished_on_timestamp(self, finished_on_timestamp): + """Sets the finished_on_timestamp of this DocumentSearch. + + + :param finished_on_timestamp: The finished_on_timestamp of this DocumentSearch. # noqa: E501 + :type: int + """ + + self._finished_on_timestamp = finished_on_timestamp + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentSearch): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/document_signer_template_conf.py b/signrequest_python_client/models/document_signer_template_conf.py new file mode 100644 index 0000000..c9a6ee1 --- /dev/null +++ b/signrequest_python_client/models/document_signer_template_conf.py @@ -0,0 +1,278 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.placeholder import Placeholder # noqa: F401,E501 + + +class DocumentSignerTemplateConf(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'signer_index': 'int', + 'needs_to_sign': 'bool', + 'approve_only': 'bool', + 'notify_only': 'bool', + 'in_person': 'bool', + 'order': 'int', + 'placeholders': 'list[Placeholder]' + } + + attribute_map = { + 'signer_index': 'signer_index', + 'needs_to_sign': 'needs_to_sign', + 'approve_only': 'approve_only', + 'notify_only': 'notify_only', + 'in_person': 'in_person', + 'order': 'order', + 'placeholders': 'placeholders' + } + + def __init__(self, signer_index=None, needs_to_sign=None, approve_only=None, notify_only=None, in_person=None, order=None, placeholders=None): # noqa: E501 + """DocumentSignerTemplateConf - a model defined in Swagger""" # noqa: E501 + + self._signer_index = None + self._needs_to_sign = None + self._approve_only = None + self._notify_only = None + self._in_person = None + self._order = None + self._placeholders = None + self.discriminator = None + + if signer_index is not None: + self.signer_index = signer_index + if needs_to_sign is not None: + self.needs_to_sign = needs_to_sign + if approve_only is not None: + self.approve_only = approve_only + if notify_only is not None: + self.notify_only = notify_only + if in_person is not None: + self.in_person = in_person + if order is not None: + self.order = order + if placeholders is not None: + self.placeholders = placeholders + + @property + def signer_index(self): + """Gets the signer_index of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: int + """ + return self._signer_index + + @signer_index.setter + def signer_index(self, signer_index): + """Sets the signer_index of this DocumentSignerTemplateConf. + + + :param signer_index: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 + :type: int + """ + if signer_index is not None and signer_index > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `signer_index`, must be a value less than or equal to `2147483647`") # noqa: E501 + if signer_index is not None and signer_index < -2147483648: # noqa: E501 + raise ValueError("Invalid value for `signer_index`, must be a value greater than or equal to `-2147483648`") # noqa: E501 + + self._signer_index = signer_index + + @property + def needs_to_sign(self): + """Gets the needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._needs_to_sign + + @needs_to_sign.setter + def needs_to_sign(self, needs_to_sign): + """Sets the needs_to_sign of this DocumentSignerTemplateConf. + + + :param needs_to_sign: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._needs_to_sign = needs_to_sign + + @property + def approve_only(self): + """Gets the approve_only of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._approve_only + + @approve_only.setter + def approve_only(self, approve_only): + """Sets the approve_only of this DocumentSignerTemplateConf. + + + :param approve_only: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._approve_only = approve_only + + @property + def notify_only(self): + """Gets the notify_only of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._notify_only + + @notify_only.setter + def notify_only(self, notify_only): + """Sets the notify_only of this DocumentSignerTemplateConf. + + + :param notify_only: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._notify_only = notify_only + + @property + def in_person(self): + """Gets the in_person of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The in_person of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._in_person + + @in_person.setter + def in_person(self, in_person): + """Sets the in_person of this DocumentSignerTemplateConf. + + + :param in_person: The in_person of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._in_person = in_person + + @property + def order(self): + """Gets the order of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The order of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: int + """ + return self._order + + @order.setter + def order(self, order): + """Sets the order of this DocumentSignerTemplateConf. + + + :param order: The order of this DocumentSignerTemplateConf. # noqa: E501 + :type: int + """ + if order is not None and order > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 + if order is not None and order < 0: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 + + self._order = order + + @property + def placeholders(self): + """Gets the placeholders of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: list[Placeholder] + """ + return self._placeholders + + @placeholders.setter + def placeholders(self, placeholders): + """Sets the placeholders of this DocumentSignerTemplateConf. + + + :param placeholders: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 + :type: list[Placeholder] + """ + + self._placeholders = placeholders + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentSignerTemplateConf): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/event.py b/signrequest_python_client/models/event.py new file mode 100644 index 0000000..4439605 --- /dev/null +++ b/signrequest_python_client/models/event.py @@ -0,0 +1,337 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document import Document # noqa: F401,E501 +from signrequest_python_client.models.signer import Signer # noqa: F401,E501 + + +class Event(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'status': 'str', + 'event_type': 'str', + 'delivered': 'bool', + 'delivered_on': 'datetime', + 'callback_status_code': 'int', + 'timestamp': 'datetime', + 'document': 'Document', + 'signer': 'Signer' + } + + attribute_map = { + 'uuid': 'uuid', + 'status': 'status', + 'event_type': 'event_type', + 'delivered': 'delivered', + 'delivered_on': 'delivered_on', + 'callback_status_code': 'callback_status_code', + 'timestamp': 'timestamp', + 'document': 'document', + 'signer': 'signer' + } + + def __init__(self, uuid=None, status=None, event_type=None, delivered=None, delivered_on=None, callback_status_code=None, timestamp=None, document=None, signer=None): # noqa: E501 + """Event - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._status = None + self._event_type = None + self._delivered = None + self._delivered_on = None + self._callback_status_code = None + self._timestamp = None + self._document = None + self._signer = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if status is not None: + self.status = status + if event_type is not None: + self.event_type = event_type + if delivered is not None: + self.delivered = delivered + if delivered_on is not None: + self.delivered_on = delivered_on + if callback_status_code is not None: + self.callback_status_code = callback_status_code + if timestamp is not None: + self.timestamp = timestamp + if document is not None: + self.document = document + if signer is not None: + self.signer = signer + + @property + def uuid(self): + """Gets the uuid of this Event. # noqa: E501 + + + :return: The uuid of this Event. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Event. + + + :param uuid: The uuid of this Event. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def status(self): + """Gets the status of this Event. # noqa: E501 + + + :return: The status of this Event. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this Event. + + + :param status: The status of this Event. # noqa: E501 + :type: str + """ + allowed_values = ["ok", "error"] # noqa: E501 + if status not in allowed_values: + raise ValueError( + "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 + .format(status, allowed_values) + ) + + self._status = status + + @property + def event_type(self): + """Gets the event_type of this Event. # noqa: E501 + + + :return: The event_type of this Event. # noqa: E501 + :rtype: str + """ + return self._event_type + + @event_type.setter + def event_type(self, event_type): + """Sets the event_type of this Event. + + + :param event_type: The event_type of this Event. # noqa: E501 + :type: str + """ + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + if event_type not in allowed_values: + raise ValueError( + "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 + .format(event_type, allowed_values) + ) + + self._event_type = event_type + + @property + def delivered(self): + """Gets the delivered of this Event. # noqa: E501 + + + :return: The delivered of this Event. # noqa: E501 + :rtype: bool + """ + return self._delivered + + @delivered.setter + def delivered(self, delivered): + """Sets the delivered of this Event. + + + :param delivered: The delivered of this Event. # noqa: E501 + :type: bool + """ + + self._delivered = delivered + + @property + def delivered_on(self): + """Gets the delivered_on of this Event. # noqa: E501 + + + :return: The delivered_on of this Event. # noqa: E501 + :rtype: datetime + """ + return self._delivered_on + + @delivered_on.setter + def delivered_on(self, delivered_on): + """Sets the delivered_on of this Event. + + + :param delivered_on: The delivered_on of this Event. # noqa: E501 + :type: datetime + """ + + self._delivered_on = delivered_on + + @property + def callback_status_code(self): + """Gets the callback_status_code of this Event. # noqa: E501 + + + :return: The callback_status_code of this Event. # noqa: E501 + :rtype: int + """ + return self._callback_status_code + + @callback_status_code.setter + def callback_status_code(self, callback_status_code): + """Sets the callback_status_code of this Event. + + + :param callback_status_code: The callback_status_code of this Event. # noqa: E501 + :type: int + """ + + self._callback_status_code = callback_status_code + + @property + def timestamp(self): + """Gets the timestamp of this Event. # noqa: E501 + + + :return: The timestamp of this Event. # noqa: E501 + :rtype: datetime + """ + return self._timestamp + + @timestamp.setter + def timestamp(self, timestamp): + """Sets the timestamp of this Event. + + + :param timestamp: The timestamp of this Event. # noqa: E501 + :type: datetime + """ + + self._timestamp = timestamp + + @property + def document(self): + """Gets the document of this Event. # noqa: E501 + + + :return: The document of this Event. # noqa: E501 + :rtype: Document + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this Event. + + + :param document: The document of this Event. # noqa: E501 + :type: Document + """ + + self._document = document + + @property + def signer(self): + """Gets the signer of this Event. # noqa: E501 + + + :return: The signer of this Event. # noqa: E501 + :rtype: Signer + """ + return self._signer + + @signer.setter + def signer(self, signer): + """Sets the signer of this Event. + + + :param signer: The signer of this Event. # noqa: E501 + :type: Signer + """ + + self._signer = signer + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Event): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/file_from_sf.py b/signrequest_python_client/models/file_from_sf.py new file mode 100644 index 0000000..987c0b2 --- /dev/null +++ b/signrequest_python_client/models/file_from_sf.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class FileFromSf(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'object_type': 'str', + 'object_id': 'str' + } + + attribute_map = { + 'object_type': 'object_type', + 'object_id': 'object_id' + } + + def __init__(self, object_type=None, object_id=None): # noqa: E501 + """FileFromSf - a model defined in Swagger""" # noqa: E501 + + self._object_type = None + self._object_id = None + self.discriminator = None + + self.object_type = object_type + self.object_id = object_id + + @property + def object_type(self): + """Gets the object_type of this FileFromSf. # noqa: E501 + + + :return: The object_type of this FileFromSf. # noqa: E501 + :rtype: str + """ + return self._object_type + + @object_type.setter + def object_type(self, object_type): + """Sets the object_type of this FileFromSf. + + + :param object_type: The object_type of this FileFromSf. # noqa: E501 + :type: str + """ + if object_type is None: + raise ValueError("Invalid value for `object_type`, must not be `None`") # noqa: E501 + if object_type is not None and len(object_type) < 1: + raise ValueError("Invalid value for `object_type`, length must be greater than or equal to `1`") # noqa: E501 + + self._object_type = object_type + + @property + def object_id(self): + """Gets the object_id of this FileFromSf. # noqa: E501 + + + :return: The object_id of this FileFromSf. # noqa: E501 + :rtype: str + """ + return self._object_id + + @object_id.setter + def object_id(self, object_id): + """Sets the object_id of this FileFromSf. + + + :param object_id: The object_id of this FileFromSf. # noqa: E501 + :type: str + """ + if object_id is None: + raise ValueError("Invalid value for `object_id`, must not be `None`") # noqa: E501 + if object_id is not None and len(object_id) < 1: + raise ValueError("Invalid value for `object_id`, length must be greater than or equal to `1`") # noqa: E501 + + self._object_id = object_id + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, FileFromSf): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_document_signer_integration_data.py b/signrequest_python_client/models/inline_document_signer_integration_data.py new file mode 100644 index 0000000..9a4c942 --- /dev/null +++ b/signrequest_python_client/models/inline_document_signer_integration_data.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineDocumentSignerIntegrationData(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, integration=None, integration_data=None): # noqa: E501 + """InlineDocumentSignerIntegrationData - a model defined in Swagger""" # noqa: E501 + + self._integration = None + self._integration_data = None + self.discriminator = None + + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def integration(self): + """Gets the integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + + + :return: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this InlineDocumentSignerIntegrationData. + + + :param integration: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + + + :return: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this InlineDocumentSignerIntegrationData. + + + :param integration_data: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineDocumentSignerIntegrationData): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_integration_data.py b/signrequest_python_client/models/inline_integration_data.py new file mode 100644 index 0000000..be4a6e8 --- /dev/null +++ b/signrequest_python_client/models/inline_integration_data.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineIntegrationData(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, integration=None, integration_data=None): # noqa: E501 + """InlineIntegrationData - a model defined in Swagger""" # noqa: E501 + + self._integration = None + self._integration_data = None + self.discriminator = None + + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def integration(self): + """Gets the integration of this InlineIntegrationData. # noqa: E501 + + + :return: The integration of this InlineIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this InlineIntegrationData. + + + :param integration: The integration of this InlineIntegrationData. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this InlineIntegrationData. # noqa: E501 + + + :return: The integration_data of this InlineIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this InlineIntegrationData. + + + :param integration_data: The integration_data of this InlineIntegrationData. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineIntegrationData): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_prefill_tags.py b/signrequest_python_client/models/inline_prefill_tags.py new file mode 100644 index 0000000..9d5b817 --- /dev/null +++ b/signrequest_python_client/models/inline_prefill_tags.py @@ -0,0 +1,192 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlinePrefillTags(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'external_id': 'str', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date' + } + + attribute_map = { + 'external_id': 'external_id', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value' + } + + def __init__(self, external_id=None, text=None, checkbox_value=None, date_value=None): # noqa: E501 + """InlinePrefillTags - a model defined in Swagger""" # noqa: E501 + + self._external_id = None + self._text = None + self._checkbox_value = None + self._date_value = None + self.discriminator = None + + if external_id is not None: + self.external_id = external_id + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this InlinePrefillTags. # noqa: E501 + + + :return: The external_id of this InlinePrefillTags. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this InlinePrefillTags. + + + :param external_id: The external_id of this InlinePrefillTags. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def text(self): + """Gets the text of this InlinePrefillTags. # noqa: E501 + + + :return: The text of this InlinePrefillTags. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this InlinePrefillTags. + + + :param text: The text of this InlinePrefillTags. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this InlinePrefillTags. # noqa: E501 + + + :return: The checkbox_value of this InlinePrefillTags. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this InlinePrefillTags. + + + :param checkbox_value: The checkbox_value of this InlinePrefillTags. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this InlinePrefillTags. # noqa: E501 + + + :return: The date_value of this InlinePrefillTags. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this InlinePrefillTags. + + + :param date_value: The date_value of this InlinePrefillTags. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlinePrefillTags): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200.py b/signrequest_python_client/models/inline_response_200.py new file mode 100644 index 0000000..44b847a --- /dev/null +++ b/signrequest_python_client/models/inline_response_200.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.auth_token import AuthToken # noqa: F401,E501 + + +class InlineResponse200(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[AuthToken]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse200 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse200. # noqa: E501 + + + :return: The count of this InlineResponse200. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse200. + + + :param count: The count of this InlineResponse200. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse200. # noqa: E501 + + + :return: The next of this InlineResponse200. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse200. + + + :param next: The next of this InlineResponse200. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse200. # noqa: E501 + + + :return: The previous of this InlineResponse200. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse200. + + + :param previous: The previous of this InlineResponse200. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse200. # noqa: E501 + + + :return: The results of this InlineResponse200. # noqa: E501 + :rtype: list[AuthToken] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse200. + + + :param results: The results of this InlineResponse200. # noqa: E501 + :type: list[AuthToken] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse200): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_1.py b/signrequest_python_client/models/inline_response_200_1.py new file mode 100644 index 0000000..10e4606 --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_1.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 + + +class InlineResponse2001(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[DocumentAttachment]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2001 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2001. # noqa: E501 + + + :return: The count of this InlineResponse2001. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2001. + + + :param count: The count of this InlineResponse2001. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2001. # noqa: E501 + + + :return: The next of this InlineResponse2001. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2001. + + + :param next: The next of this InlineResponse2001. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2001. # noqa: E501 + + + :return: The previous of this InlineResponse2001. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2001. + + + :param previous: The previous of this InlineResponse2001. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2001. # noqa: E501 + + + :return: The results of this InlineResponse2001. # noqa: E501 + :rtype: list[DocumentAttachment] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2001. + + + :param results: The results of this InlineResponse2001. # noqa: E501 + :type: list[DocumentAttachment] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2001): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_2.py b/signrequest_python_client/models/inline_response_200_2.py new file mode 100644 index 0000000..748c3af --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_2.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document_search import DocumentSearch # noqa: F401,E501 + + +class InlineResponse2002(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[DocumentSearch]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2002 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2002. # noqa: E501 + + + :return: The count of this InlineResponse2002. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2002. + + + :param count: The count of this InlineResponse2002. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2002. # noqa: E501 + + + :return: The next of this InlineResponse2002. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2002. + + + :param next: The next of this InlineResponse2002. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2002. # noqa: E501 + + + :return: The previous of this InlineResponse2002. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2002. + + + :param previous: The previous of this InlineResponse2002. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2002. # noqa: E501 + + + :return: The results of this InlineResponse2002. # noqa: E501 + :rtype: list[DocumentSearch] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2002. + + + :param results: The results of this InlineResponse2002. # noqa: E501 + :type: list[DocumentSearch] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2002): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_3.py b/signrequest_python_client/models/inline_response_200_3.py new file mode 100644 index 0000000..de24862 --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_3.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document import Document # noqa: F401,E501 + + +class InlineResponse2003(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Document]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2003 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2003. # noqa: E501 + + + :return: The count of this InlineResponse2003. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2003. + + + :param count: The count of this InlineResponse2003. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2003. # noqa: E501 + + + :return: The next of this InlineResponse2003. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2003. + + + :param next: The next of this InlineResponse2003. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2003. # noqa: E501 + + + :return: The previous of this InlineResponse2003. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2003. + + + :param previous: The previous of this InlineResponse2003. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2003. # noqa: E501 + + + :return: The results of this InlineResponse2003. # noqa: E501 + :rtype: list[Document] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2003. + + + :param results: The results of this InlineResponse2003. # noqa: E501 + :type: list[Document] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2003): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_4.py b/signrequest_python_client/models/inline_response_200_4.py new file mode 100644 index 0000000..6c09b68 --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_4.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.event import Event # noqa: F401,E501 + + +class InlineResponse2004(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Event]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2004 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2004. # noqa: E501 + + + :return: The count of this InlineResponse2004. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2004. + + + :param count: The count of this InlineResponse2004. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2004. # noqa: E501 + + + :return: The next of this InlineResponse2004. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2004. + + + :param next: The next of this InlineResponse2004. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2004. # noqa: E501 + + + :return: The previous of this InlineResponse2004. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2004. + + + :param previous: The previous of this InlineResponse2004. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2004. # noqa: E501 + + + :return: The results of this InlineResponse2004. # noqa: E501 + :rtype: list[Event] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2004. + + + :param results: The results of this InlineResponse2004. # noqa: E501 + :type: list[Event] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2004): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_5.py b/signrequest_python_client/models/inline_response_200_5.py new file mode 100644 index 0000000..80df36f --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_5.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.sign_request import SignRequest # noqa: F401,E501 + + +class InlineResponse2005(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[SignRequest]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2005 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2005. # noqa: E501 + + + :return: The count of this InlineResponse2005. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2005. + + + :param count: The count of this InlineResponse2005. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2005. # noqa: E501 + + + :return: The next of this InlineResponse2005. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2005. + + + :param next: The next of this InlineResponse2005. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2005. # noqa: E501 + + + :return: The previous of this InlineResponse2005. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2005. + + + :param previous: The previous of this InlineResponse2005. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2005. # noqa: E501 + + + :return: The results of this InlineResponse2005. # noqa: E501 + :rtype: list[SignRequest] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2005. + + + :param results: The results of this InlineResponse2005. # noqa: E501 + :type: list[SignRequest] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2005): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_6.py b/signrequest_python_client/models/inline_response_200_6.py new file mode 100644 index 0000000..036a14c --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_6.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.team_member import TeamMember # noqa: F401,E501 + + +class InlineResponse2006(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[TeamMember]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2006 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2006. # noqa: E501 + + + :return: The count of this InlineResponse2006. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2006. + + + :param count: The count of this InlineResponse2006. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2006. # noqa: E501 + + + :return: The next of this InlineResponse2006. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2006. + + + :param next: The next of this InlineResponse2006. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2006. # noqa: E501 + + + :return: The previous of this InlineResponse2006. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2006. + + + :param previous: The previous of this InlineResponse2006. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2006. # noqa: E501 + + + :return: The results of this InlineResponse2006. # noqa: E501 + :rtype: list[TeamMember] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2006. + + + :param results: The results of this InlineResponse2006. # noqa: E501 + :type: list[TeamMember] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2006): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_7.py b/signrequest_python_client/models/inline_response_200_7.py new file mode 100644 index 0000000..4f97afe --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_7.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.team import Team # noqa: F401,E501 + + +class InlineResponse2007(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Team]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2007 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2007. # noqa: E501 + + + :return: The count of this InlineResponse2007. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2007. + + + :param count: The count of this InlineResponse2007. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2007. # noqa: E501 + + + :return: The next of this InlineResponse2007. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2007. + + + :param next: The next of this InlineResponse2007. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2007. # noqa: E501 + + + :return: The previous of this InlineResponse2007. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2007. + + + :param previous: The previous of this InlineResponse2007. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2007. # noqa: E501 + + + :return: The results of this InlineResponse2007. # noqa: E501 + :rtype: list[Team] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2007. + + + :param results: The results of this InlineResponse2007. # noqa: E501 + :type: list[Team] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2007): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_8.py b/signrequest_python_client/models/inline_response_200_8.py new file mode 100644 index 0000000..72f4967 --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_8.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.template import Template # noqa: F401,E501 + + +class InlineResponse2008(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Template]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2008 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2008. # noqa: E501 + + + :return: The count of this InlineResponse2008. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2008. + + + :param count: The count of this InlineResponse2008. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2008. # noqa: E501 + + + :return: The next of this InlineResponse2008. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2008. + + + :param next: The next of this InlineResponse2008. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2008. # noqa: E501 + + + :return: The previous of this InlineResponse2008. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2008. + + + :param previous: The previous of this InlineResponse2008. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2008. # noqa: E501 + + + :return: The results of this InlineResponse2008. # noqa: E501 + :rtype: list[Template] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2008. + + + :param results: The results of this InlineResponse2008. # noqa: E501 + :type: list[Template] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2008): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_200_9.py b/signrequest_python_client/models/inline_response_200_9.py new file mode 100644 index 0000000..7087499 --- /dev/null +++ b/signrequest_python_client/models/inline_response_200_9.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.webhook_subscription import WebhookSubscription # noqa: F401,E501 + + +class InlineResponse2009(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[WebhookSubscription]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2009 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2009. # noqa: E501 + + + :return: The count of this InlineResponse2009. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2009. + + + :param count: The count of this InlineResponse2009. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2009. # noqa: E501 + + + :return: The next of this InlineResponse2009. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2009. + + + :param next: The next of this InlineResponse2009. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2009. # noqa: E501 + + + :return: The previous of this InlineResponse2009. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2009. + + + :param previous: The previous of this InlineResponse2009. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2009. # noqa: E501 + + + :return: The results of this InlineResponse2009. # noqa: E501 + :rtype: list[WebhookSubscription] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2009. + + + :param results: The results of this InlineResponse2009. # noqa: E501 + :type: list[WebhookSubscription] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2009): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_sign_request.py b/signrequest_python_client/models/inline_sign_request.py new file mode 100644 index 0000000..24b2505 --- /dev/null +++ b/signrequest_python_client/models/inline_sign_request.py @@ -0,0 +1,607 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_python_client.models.signer import Signer # noqa: F401,E501 + + +class InlineSignRequest(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who=None, send_reminders=None, signers=None, uuid=None): # noqa: E501 + """InlineSignRequest - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self.discriminator = None + + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + self.signers = signers + if uuid is not None: + self.uuid = uuid + + @property + def from_email(self): + """Gets the from_email of this InlineSignRequest. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this InlineSignRequest. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this InlineSignRequest. # noqa: E501 + :type: str + """ + if from_email is None: + raise ValueError("Invalid value for `from_email`, must not be `None`") # noqa: E501 + if from_email is not None and len(from_email) > 255: + raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this InlineSignRequest. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this InlineSignRequest. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this InlineSignRequest. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) > 255: + raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this InlineSignRequest. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this InlineSignRequest. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this InlineSignRequest. # noqa: E501 + + + :return: The prepare_url of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this InlineSignRequest. + + + :param prepare_url: The prepare_url of this InlineSignRequest. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this InlineSignRequest. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this InlineSignRequest. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this InlineSignRequest. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this InlineSignRequest. # noqa: E501 + + + :return: The required_attachments of this InlineSignRequest. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this InlineSignRequest. + + + :param required_attachments: The required_attachments of this InlineSignRequest. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this InlineSignRequest. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this InlineSignRequest. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this InlineSignRequest. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this InlineSignRequest. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this InlineSignRequest. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this InlineSignRequest. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this InlineSignRequest. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this InlineSignRequest. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this InlineSignRequest. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this InlineSignRequest. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this InlineSignRequest. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this InlineSignRequest. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this InlineSignRequest. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this InlineSignRequest. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this InlineSignRequest. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) > 512: + raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this InlineSignRequest. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this InlineSignRequest. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this InlineSignRequest. # noqa: E501 + :type: str + """ + + self._message = message + + @property + def who(self): + """Gets the who of this InlineSignRequest. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this InlineSignRequest. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this InlineSignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this InlineSignRequest. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this InlineSignRequest. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this InlineSignRequest. # noqa: E501 + + + :return: The signers of this InlineSignRequest. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this InlineSignRequest. + + + :param signers: The signers of this InlineSignRequest. # noqa: E501 + :type: list[Signer] + """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this InlineSignRequest. # noqa: E501 + + + :return: The uuid of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this InlineSignRequest. + + + :param uuid: The uuid of this InlineSignRequest. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineSignRequest): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_team.py b/signrequest_python_client/models/inline_team.py new file mode 100644 index 0000000..dacb2bd --- /dev/null +++ b/signrequest_python_client/models/inline_team.py @@ -0,0 +1,170 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineTeam(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'subdomain': 'str', + 'url': 'str' + } + + attribute_map = { + 'name': 'name', + 'subdomain': 'subdomain', + 'url': 'url' + } + + def __init__(self, name=None, subdomain=None, url=None): # noqa: E501 + """InlineTeam - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._subdomain = None + self._url = None + self.discriminator = None + + if name is not None: + self.name = name + if subdomain is not None: + self.subdomain = subdomain + if url is not None: + self.url = url + + @property + def name(self): + """Gets the name of this InlineTeam. # noqa: E501 + + + :return: The name of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this InlineTeam. + + + :param name: The name of this InlineTeam. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def subdomain(self): + """Gets the subdomain of this InlineTeam. # noqa: E501 + + + :return: The subdomain of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this InlineTeam. + + + :param subdomain: The subdomain of this InlineTeam. # noqa: E501 + :type: str + """ + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 + raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 + + self._subdomain = subdomain + + @property + def url(self): + """Gets the url of this InlineTeam. # noqa: E501 + + + :return: The url of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this InlineTeam. + + + :param url: The url of this InlineTeam. # noqa: E501 + :type: str + """ + + self._url = url + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineTeam): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_team_member.py b/signrequest_python_client/models/inline_team_member.py new file mode 100644 index 0000000..876d465 --- /dev/null +++ b/signrequest_python_client/models/inline_team_member.py @@ -0,0 +1,246 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.user import User # noqa: F401,E501 + + +class InlineTeamMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'url': 'str', + 'user': 'User', + 'is_admin': 'bool', + 'is_active': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'uuid': 'uuid', + 'url': 'url', + 'user': 'user', + 'is_admin': 'is_admin', + 'is_active': 'is_active', + 'is_owner': 'is_owner' + } + + def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 + """InlineTeamMember - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._url = None + self._user = None + self._is_admin = None + self._is_active = None + self._is_owner = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if user is not None: + self.user = user + if is_admin is not None: + self.is_admin = is_admin + if is_active is not None: + self.is_active = is_active + if is_owner is not None: + self.is_owner = is_owner + + @property + def uuid(self): + """Gets the uuid of this InlineTeamMember. # noqa: E501 + + + :return: The uuid of this InlineTeamMember. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this InlineTeamMember. + + + :param uuid: The uuid of this InlineTeamMember. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this InlineTeamMember. # noqa: E501 + + + :return: The url of this InlineTeamMember. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this InlineTeamMember. + + + :param url: The url of this InlineTeamMember. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def user(self): + """Gets the user of this InlineTeamMember. # noqa: E501 + + + :return: The user of this InlineTeamMember. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this InlineTeamMember. + + + :param user: The user of this InlineTeamMember. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def is_admin(self): + """Gets the is_admin of this InlineTeamMember. # noqa: E501 + + + :return: The is_admin of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this InlineTeamMember. + + + :param is_admin: The is_admin of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_active(self): + """Gets the is_active of this InlineTeamMember. # noqa: E501 + + + :return: The is_active of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_active + + @is_active.setter + def is_active(self, is_active): + """Sets the is_active of this InlineTeamMember. + + + :param is_active: The is_active of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_active = is_active + + @property + def is_owner(self): + """Gets the is_owner of this InlineTeamMember. # noqa: E501 + + + :return: The is_owner of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this InlineTeamMember. + + + :param is_owner: The is_owner of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineTeamMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/invite_member.py b/signrequest_python_client/models/invite_member.py new file mode 100644 index 0000000..62e15f6 --- /dev/null +++ b/signrequest_python_client/models/invite_member.py @@ -0,0 +1,167 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InviteMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'is_admin': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'email': 'email', + 'is_admin': 'is_admin', + 'is_owner': 'is_owner' + } + + def __init__(self, email=None, is_admin=False, is_owner=False): # noqa: E501 + """InviteMember - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._is_admin = None + self._is_owner = None + self.discriminator = None + + self.email = email + if is_admin is not None: + self.is_admin = is_admin + if is_owner is not None: + self.is_owner = is_owner + + @property + def email(self): + """Gets the email of this InviteMember. # noqa: E501 + + + :return: The email of this InviteMember. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this InviteMember. + + + :param email: The email of this InviteMember. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def is_admin(self): + """Gets the is_admin of this InviteMember. # noqa: E501 + + + :return: The is_admin of this InviteMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this InviteMember. + + + :param is_admin: The is_admin of this InviteMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_owner(self): + """Gets the is_owner of this InviteMember. # noqa: E501 + + + :return: The is_owner of this InviteMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this InviteMember. + + + :param is_owner: The is_owner of this InviteMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InviteMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/placeholder.py b/signrequest_python_client/models/placeholder.py new file mode 100644 index 0000000..05ee1a4 --- /dev/null +++ b/signrequest_python_client/models/placeholder.py @@ -0,0 +1,306 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class Placeholder(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'type': 'str', + 'page_index': 'int', + 'prefill': 'bool', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date', + 'external_id': 'str' + } + + attribute_map = { + 'uuid': 'uuid', + 'type': 'type', + 'page_index': 'page_index', + 'prefill': 'prefill', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value', + 'external_id': 'external_id' + } + + def __init__(self, uuid=None, type=None, page_index=None, prefill=None, text=None, checkbox_value=None, date_value=None, external_id=None): # noqa: E501 + """Placeholder - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._type = None + self._page_index = None + self._prefill = None + self._text = None + self._checkbox_value = None + self._date_value = None + self._external_id = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if type is not None: + self.type = type + self.page_index = page_index + self.prefill = prefill + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + if external_id is not None: + self.external_id = external_id + + @property + def uuid(self): + """Gets the uuid of this Placeholder. # noqa: E501 + + + :return: The uuid of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Placeholder. + + + :param uuid: The uuid of this Placeholder. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def type(self): + """Gets the type of this Placeholder. # noqa: E501 + + + :return: The type of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._type + + @type.setter + def type(self, type): + """Sets the type of this Placeholder. + + + :param type: The type of this Placeholder. # noqa: E501 + :type: str + """ + allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 + if type not in allowed_values: + raise ValueError( + "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 + .format(type, allowed_values) + ) + + self._type = type + + @property + def page_index(self): + """Gets the page_index of this Placeholder. # noqa: E501 + + + :return: The page_index of this Placeholder. # noqa: E501 + :rtype: int + """ + return self._page_index + + @page_index.setter + def page_index(self, page_index): + """Sets the page_index of this Placeholder. + + + :param page_index: The page_index of this Placeholder. # noqa: E501 + :type: int + """ + if page_index is None: + raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 + + self._page_index = page_index + + @property + def prefill(self): + """Gets the prefill of this Placeholder. # noqa: E501 + + + :return: The prefill of this Placeholder. # noqa: E501 + :rtype: bool + """ + return self._prefill + + @prefill.setter + def prefill(self, prefill): + """Sets the prefill of this Placeholder. + + + :param prefill: The prefill of this Placeholder. # noqa: E501 + :type: bool + """ + if prefill is None: + raise ValueError("Invalid value for `prefill`, must not be `None`") # noqa: E501 + + self._prefill = prefill + + @property + def text(self): + """Gets the text of this Placeholder. # noqa: E501 + + + :return: The text of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this Placeholder. + + + :param text: The text of this Placeholder. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this Placeholder. # noqa: E501 + + + :return: The checkbox_value of this Placeholder. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this Placeholder. + + + :param checkbox_value: The checkbox_value of this Placeholder. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this Placeholder. # noqa: E501 + + + :return: The date_value of this Placeholder. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this Placeholder. + + + :param date_value: The date_value of this Placeholder. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this Placeholder. # noqa: E501 + + + :return: The external_id of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this Placeholder. + + + :param external_id: The external_id of this Placeholder. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Placeholder): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/required_attachment.py b/signrequest_python_client/models/required_attachment.py new file mode 100644 index 0000000..f44336b --- /dev/null +++ b/signrequest_python_client/models/required_attachment.py @@ -0,0 +1,145 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class RequiredAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'uuid': 'str' + } + + attribute_map = { + 'name': 'name', + 'uuid': 'uuid' + } + + def __init__(self, name=None, uuid=None): # noqa: E501 + """RequiredAttachment - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._uuid = None + self.discriminator = None + + self.name = name + if uuid is not None: + self.uuid = uuid + + @property + def name(self): + """Gets the name of this RequiredAttachment. # noqa: E501 + + + :return: The name of this RequiredAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this RequiredAttachment. + + + :param name: The name of this RequiredAttachment. # noqa: E501 + :type: str + """ + if name is None: + raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def uuid(self): + """Gets the uuid of this RequiredAttachment. # noqa: E501 + + + :return: The uuid of this RequiredAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this RequiredAttachment. + + + :param uuid: The uuid of this RequiredAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, RequiredAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py new file mode 100644 index 0000000..f069864 --- /dev/null +++ b/signrequest_python_client/models/sign_request.py @@ -0,0 +1,719 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_python_client.models.signer import Signer # noqa: F401,E501 + + +class SignRequest(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str', + 'url': 'str', + 'document': 'str', + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid', + 'url': 'url', + 'document': 'document', + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None): # noqa: E501 + """SignRequest - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self._url = None + self._document = None + self._integration = None + self._integration_data = None + self.discriminator = None + + if from_email is not None: + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + self.signers = signers + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + self.document = document + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def from_email(self): + """Gets the from_email of this SignRequest. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this SignRequest. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this SignRequest. # noqa: E501 + :type: str + """ + if from_email is not None and len(from_email) > 255: + raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this SignRequest. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this SignRequest. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this SignRequest. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) > 255: + raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this SignRequest. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this SignRequest. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this SignRequest. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this SignRequest. # noqa: E501 + + + :return: The prepare_url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this SignRequest. + + + :param prepare_url: The prepare_url of this SignRequest. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this SignRequest. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this SignRequest. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this SignRequest. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this SignRequest. # noqa: E501 + + Attachments that signers are required to upload # noqa: E501 + + :return: The required_attachments of this SignRequest. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this SignRequest. + + Attachments that signers are required to upload # noqa: E501 + + :param required_attachments: The required_attachments of this SignRequest. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this SignRequest. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this SignRequest. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this SignRequest. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this SignRequest. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this SignRequest. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this SignRequest. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this SignRequest. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this SignRequest. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this SignRequest. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this SignRequest. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this SignRequest. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this SignRequest. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this SignRequest. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this SignRequest. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this SignRequest. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) > 512: + raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this SignRequest. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this SignRequest. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this SignRequest. # noqa: E501 + :type: str + """ + + self._message = message + + @property + def who(self): + """Gets the who of this SignRequest. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this SignRequest. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this SignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this SignRequest. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this SignRequest. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this SignRequest. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this SignRequest. # noqa: E501 + + + :return: The signers of this SignRequest. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this SignRequest. + + + :param signers: The signers of this SignRequest. # noqa: E501 + :type: list[Signer] + """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this SignRequest. # noqa: E501 + + + :return: The uuid of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignRequest. + + + :param uuid: The uuid of this SignRequest. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this SignRequest. # noqa: E501 + + + :return: The url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this SignRequest. + + + :param url: The url of this SignRequest. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def document(self): + """Gets the document of this SignRequest. # noqa: E501 + + + :return: The document of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this SignRequest. + + + :param document: The document of this SignRequest. # noqa: E501 + :type: str + """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 + + self._document = document + + @property + def integration(self): + """Gets the integration of this SignRequest. # noqa: E501 + + + :return: The integration of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this SignRequest. + + + :param integration: The integration of this SignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this SignRequest. # noqa: E501 + + + :return: The integration_data of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this SignRequest. + + + :param integration_data: The integration_data of this SignRequest. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignRequest): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/sign_request_quick_create.py b/signrequest_python_client/models/sign_request_quick_create.py new file mode 100644 index 0000000..59d98c7 --- /dev/null +++ b/signrequest_python_client/models/sign_request_quick_create.py @@ -0,0 +1,1093 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: F401,E501 +from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 +from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 +from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_python_client.models.signer import Signer # noqa: F401,E501 + + +class SignRequestQuickCreate(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str', + 'url': 'str', + 'document': 'str', + 'integration': 'str', + 'integration_data': 'str', + 'name': 'str', + 'external_id': 'str', + 'frontend_id': 'str', + 'file': 'str', + 'file_from_url': 'str', + 'events_callback_url': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'template': 'str', + 'prefill_tags': 'list[InlinePrefillTags]', + 'integrations': 'list[InlineIntegrationData]', + 'file_from_sf': 'FileFromSf', + 'auto_delete_days': 'int' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid', + 'url': 'url', + 'document': 'document', + 'integration': 'integration', + 'integration_data': 'integration_data', + 'name': 'name', + 'external_id': 'external_id', + 'frontend_id': 'frontend_id', + 'file': 'file', + 'file_from_url': 'file_from_url', + 'events_callback_url': 'events_callback_url', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'template': 'template', + 'prefill_tags': 'prefill_tags', + 'integrations': 'integrations', + 'file_from_sf': 'file_from_sf', + 'auto_delete_days': 'auto_delete_days' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None): # noqa: E501 + """SignRequestQuickCreate - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self._url = None + self._document = None + self._integration = None + self._integration_data = None + self._name = None + self._external_id = None + self._frontend_id = None + self._file = None + self._file_from_url = None + self._events_callback_url = None + self._file_from_content = None + self._file_from_content_name = None + self._template = None + self._prefill_tags = None + self._integrations = None + self._file_from_sf = None + self._auto_delete_days = None + self.discriminator = None + + if from_email is not None: + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + self.signers = signers + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if document is not None: + self.document = document + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + if name is not None: + self.name = name + if external_id is not None: + self.external_id = external_id + if frontend_id is not None: + self.frontend_id = frontend_id + if file is not None: + self.file = file + if file_from_url is not None: + self.file_from_url = file_from_url + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if template is not None: + self.template = template + if prefill_tags is not None: + self.prefill_tags = prefill_tags + if integrations is not None: + self.integrations = integrations + if file_from_sf is not None: + self.file_from_sf = file_from_sf + if auto_delete_days is not None: + self.auto_delete_days = auto_delete_days + + @property + def from_email(self): + """Gets the from_email of this SignRequestQuickCreate. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this SignRequestQuickCreate. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if from_email is not None and len(from_email) > 255: + raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this SignRequestQuickCreate. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this SignRequestQuickCreate. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) > 255: + raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this SignRequestQuickCreate. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this SignRequestQuickCreate. # noqa: E501 + + + :return: The prepare_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this SignRequestQuickCreate. + + + :param prepare_url: The prepare_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this SignRequestQuickCreate. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this SignRequestQuickCreate. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this SignRequestQuickCreate. # noqa: E501 + + Attachments that signers are required to upload # noqa: E501 + + :return: The required_attachments of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this SignRequestQuickCreate. + + Attachments that signers are required to upload # noqa: E501 + + :param required_attachments: The required_attachments of this SignRequestQuickCreate. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this SignRequestQuickCreate. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this SignRequestQuickCreate. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this SignRequestQuickCreate. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this SignRequestQuickCreate. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this SignRequestQuickCreate. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this SignRequestQuickCreate. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this SignRequestQuickCreate. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this SignRequestQuickCreate. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this SignRequestQuickCreate. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this SignRequestQuickCreate. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this SignRequestQuickCreate. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this SignRequestQuickCreate. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) > 512: + raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this SignRequestQuickCreate. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this SignRequestQuickCreate. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._message = message + + @property + def who(self): + """Gets the who of this SignRequestQuickCreate. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this SignRequestQuickCreate. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this SignRequestQuickCreate. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this SignRequestQuickCreate. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this SignRequestQuickCreate. # noqa: E501 + + + :return: The signers of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this SignRequestQuickCreate. + + + :param signers: The signers of this SignRequestQuickCreate. # noqa: E501 + :type: list[Signer] + """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this SignRequestQuickCreate. # noqa: E501 + + + :return: The uuid of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignRequestQuickCreate. + + + :param uuid: The uuid of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this SignRequestQuickCreate. # noqa: E501 + + + :return: The url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this SignRequestQuickCreate. + + + :param url: The url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def document(self): + """Gets the document of this SignRequestQuickCreate. # noqa: E501 + + + :return: The document of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this SignRequestQuickCreate. + + + :param document: The document of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._document = document + + @property + def integration(self): + """Gets the integration of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integration of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this SignRequestQuickCreate. + + + :param integration: The integration of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integration_data of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this SignRequestQuickCreate. + + + :param integration_data: The integration_data of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + @property + def name(self): + """Gets the name of this SignRequestQuickCreate. # noqa: E501 + + Defaults to filename, including extension # noqa: E501 + + :return: The name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this SignRequestQuickCreate. + + Defaults to filename, including extension # noqa: E501 + + :param name: The name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def external_id(self): + """Gets the external_id of this SignRequestQuickCreate. # noqa: E501 + + ID used to reference document in external system # noqa: E501 + + :return: The external_id of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this SignRequestQuickCreate. + + ID used to reference document in external system # noqa: E501 + + :param external_id: The external_id of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def frontend_id(self): + """Gets the frontend_id of this SignRequestQuickCreate. # noqa: E501 + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :return: The frontend_id of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._frontend_id + + @frontend_id.setter + def frontend_id(self, frontend_id): + """Sets the frontend_id of this SignRequestQuickCreate. + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :param frontend_id: The frontend_id of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if frontend_id is not None and len(frontend_id) > 255: + raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 + + self._frontend_id = frontend_id + + @property + def file(self): + """Gets the file of this SignRequestQuickCreate. # noqa: E501 + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :return: The file of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this SignRequestQuickCreate. + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :param file: The file of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_url(self): + """Gets the file_from_url of this SignRequestQuickCreate. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this SignRequestQuickCreate. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def events_callback_url(self): + """Gets the events_callback_url of this SignRequestQuickCreate. # noqa: E501 + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :return: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this SignRequestQuickCreate. + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :param events_callback_url: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def file_from_content(self): + """Gets the file_from_content of this SignRequestQuickCreate. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this SignRequestQuickCreate. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this SignRequestQuickCreate. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def template(self): + """Gets the template of this SignRequestQuickCreate. # noqa: E501 + + + :return: The template of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._template + + @template.setter + def template(self, template): + """Sets the template of this SignRequestQuickCreate. + + + :param template: The template of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._template = template + + @property + def prefill_tags(self): + """Gets the prefill_tags of this SignRequestQuickCreate. # noqa: E501 + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :return: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[InlinePrefillTags] + """ + return self._prefill_tags + + @prefill_tags.setter + def prefill_tags(self, prefill_tags): + """Sets the prefill_tags of this SignRequestQuickCreate. + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :param prefill_tags: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 + :type: list[InlinePrefillTags] + """ + + self._prefill_tags = prefill_tags + + @property + def integrations(self): + """Gets the integrations of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integrations of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[InlineIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this SignRequestQuickCreate. + + + :param integrations: The integrations of this SignRequestQuickCreate. # noqa: E501 + :type: list[InlineIntegrationData] + """ + + self._integrations = integrations + + @property + def file_from_sf(self): + """Gets the file_from_sf of this SignRequestQuickCreate. # noqa: E501 + + + :return: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 + :rtype: FileFromSf + """ + return self._file_from_sf + + @file_from_sf.setter + def file_from_sf(self, file_from_sf): + """Sets the file_from_sf of this SignRequestQuickCreate. + + + :param file_from_sf: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 + :type: FileFromSf + """ + + self._file_from_sf = file_from_sf + + @property + def auto_delete_days(self): + """Gets the auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + :rtype: int + """ + return self._auto_delete_days + + @auto_delete_days.setter + def auto_delete_days(self, auto_delete_days): + """Sets the auto_delete_days of this SignRequestQuickCreate. + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_days: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + :type: int + """ + if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 + if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 + + self._auto_delete_days = auto_delete_days + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignRequestQuickCreate): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/signer.py b/signrequest_python_client/models/signer.py new file mode 100644 index 0000000..888fdd1 --- /dev/null +++ b/signrequest_python_client/models/signer.py @@ -0,0 +1,985 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData # noqa: F401,E501 +from signrequest_python_client.models.signer_attachment import SignerAttachment # noqa: F401,E501 +from signrequest_python_client.models.signer_inputs import SignerInputs # noqa: F401,E501 + + +class Signer(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'display_name': 'str', + 'first_name': 'str', + 'last_name': 'str', + 'email_viewed': 'bool', + 'viewed': 'bool', + 'signed': 'bool', + 'downloaded': 'bool', + 'signed_on': 'datetime', + 'needs_to_sign': 'bool', + 'approve_only': 'bool', + 'notify_only': 'bool', + 'in_person': 'bool', + 'order': 'int', + 'language': 'str', + 'force_language': 'bool', + 'emailed': 'bool', + 'verify_phone_number': 'str', + 'verify_bank_account': 'str', + 'declined': 'bool', + 'declined_on': 'datetime', + 'forwarded': 'str', + 'forwarded_on': 'datetime', + 'forwarded_to_email': 'str', + 'forwarded_reason': 'str', + 'message': 'str', + 'embed_url_user_id': 'str', + 'inputs': 'list[SignerInputs]', + 'embed_url': 'str', + 'attachments': 'list[SignerAttachment]', + 'redirect_url': 'str', + 'after_document': 'str', + 'integrations': 'list[InlineDocumentSignerIntegrationData]' + } + + attribute_map = { + 'email': 'email', + 'display_name': 'display_name', + 'first_name': 'first_name', + 'last_name': 'last_name', + 'email_viewed': 'email_viewed', + 'viewed': 'viewed', + 'signed': 'signed', + 'downloaded': 'downloaded', + 'signed_on': 'signed_on', + 'needs_to_sign': 'needs_to_sign', + 'approve_only': 'approve_only', + 'notify_only': 'notify_only', + 'in_person': 'in_person', + 'order': 'order', + 'language': 'language', + 'force_language': 'force_language', + 'emailed': 'emailed', + 'verify_phone_number': 'verify_phone_number', + 'verify_bank_account': 'verify_bank_account', + 'declined': 'declined', + 'declined_on': 'declined_on', + 'forwarded': 'forwarded', + 'forwarded_on': 'forwarded_on', + 'forwarded_to_email': 'forwarded_to_email', + 'forwarded_reason': 'forwarded_reason', + 'message': 'message', + 'embed_url_user_id': 'embed_url_user_id', + 'inputs': 'inputs', + 'embed_url': 'embed_url', + 'attachments': 'attachments', + 'redirect_url': 'redirect_url', + 'after_document': 'after_document', + 'integrations': 'integrations' + } + + def __init__(self, email=None, display_name=None, first_name=None, last_name=None, email_viewed=None, viewed=None, signed=None, downloaded=None, signed_on=None, needs_to_sign=True, approve_only=None, notify_only=None, in_person=None, order=None, language=None, force_language=None, emailed=None, verify_phone_number=None, verify_bank_account=None, declined=None, declined_on=None, forwarded=None, forwarded_on=None, forwarded_to_email=None, forwarded_reason=None, message=None, embed_url_user_id=None, inputs=None, embed_url=None, attachments=None, redirect_url=None, after_document=None, integrations=None): # noqa: E501 + """Signer - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._display_name = None + self._first_name = None + self._last_name = None + self._email_viewed = None + self._viewed = None + self._signed = None + self._downloaded = None + self._signed_on = None + self._needs_to_sign = None + self._approve_only = None + self._notify_only = None + self._in_person = None + self._order = None + self._language = None + self._force_language = None + self._emailed = None + self._verify_phone_number = None + self._verify_bank_account = None + self._declined = None + self._declined_on = None + self._forwarded = None + self._forwarded_on = None + self._forwarded_to_email = None + self._forwarded_reason = None + self._message = None + self._embed_url_user_id = None + self._inputs = None + self._embed_url = None + self._attachments = None + self._redirect_url = None + self._after_document = None + self._integrations = None + self.discriminator = None + + self.email = email + if display_name is not None: + self.display_name = display_name + if first_name is not None: + self.first_name = first_name + if last_name is not None: + self.last_name = last_name + if email_viewed is not None: + self.email_viewed = email_viewed + if viewed is not None: + self.viewed = viewed + if signed is not None: + self.signed = signed + if downloaded is not None: + self.downloaded = downloaded + if signed_on is not None: + self.signed_on = signed_on + if needs_to_sign is not None: + self.needs_to_sign = needs_to_sign + if approve_only is not None: + self.approve_only = approve_only + if notify_only is not None: + self.notify_only = notify_only + if in_person is not None: + self.in_person = in_person + if order is not None: + self.order = order + if language is not None: + self.language = language + if force_language is not None: + self.force_language = force_language + if emailed is not None: + self.emailed = emailed + if verify_phone_number is not None: + self.verify_phone_number = verify_phone_number + if verify_bank_account is not None: + self.verify_bank_account = verify_bank_account + if declined is not None: + self.declined = declined + if declined_on is not None: + self.declined_on = declined_on + if forwarded is not None: + self.forwarded = forwarded + if forwarded_on is not None: + self.forwarded_on = forwarded_on + if forwarded_to_email is not None: + self.forwarded_to_email = forwarded_to_email + if forwarded_reason is not None: + self.forwarded_reason = forwarded_reason + if message is not None: + self.message = message + if embed_url_user_id is not None: + self.embed_url_user_id = embed_url_user_id + if inputs is not None: + self.inputs = inputs + if embed_url is not None: + self.embed_url = embed_url + if attachments is not None: + self.attachments = attachments + if redirect_url is not None: + self.redirect_url = redirect_url + if after_document is not None: + self.after_document = after_document + if integrations is not None: + self.integrations = integrations + + @property + def email(self): + """Gets the email of this Signer. # noqa: E501 + + + :return: The email of this Signer. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this Signer. + + + :param email: The email of this Signer. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) > 255: + raise ValueError("Invalid value for `email`, length must be less than or equal to `255`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def display_name(self): + """Gets the display_name of this Signer. # noqa: E501 + + + :return: The display_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._display_name + + @display_name.setter + def display_name(self, display_name): + """Sets the display_name of this Signer. + + + :param display_name: The display_name of this Signer. # noqa: E501 + :type: str + """ + if display_name is not None and len(display_name) < 1: + raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 + + self._display_name = display_name + + @property + def first_name(self): + """Gets the first_name of this Signer. # noqa: E501 + + + :return: The first_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._first_name + + @first_name.setter + def first_name(self, first_name): + """Sets the first_name of this Signer. + + + :param first_name: The first_name of this Signer. # noqa: E501 + :type: str + """ + if first_name is not None and len(first_name) > 255: + raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 + + self._first_name = first_name + + @property + def last_name(self): + """Gets the last_name of this Signer. # noqa: E501 + + + :return: The last_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._last_name + + @last_name.setter + def last_name(self, last_name): + """Sets the last_name of this Signer. + + + :param last_name: The last_name of this Signer. # noqa: E501 + :type: str + """ + if last_name is not None and len(last_name) > 255: + raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 + + self._last_name = last_name + + @property + def email_viewed(self): + """Gets the email_viewed of this Signer. # noqa: E501 + + + :return: The email_viewed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._email_viewed + + @email_viewed.setter + def email_viewed(self, email_viewed): + """Sets the email_viewed of this Signer. + + + :param email_viewed: The email_viewed of this Signer. # noqa: E501 + :type: bool + """ + + self._email_viewed = email_viewed + + @property + def viewed(self): + """Gets the viewed of this Signer. # noqa: E501 + + + :return: The viewed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._viewed + + @viewed.setter + def viewed(self, viewed): + """Sets the viewed of this Signer. + + + :param viewed: The viewed of this Signer. # noqa: E501 + :type: bool + """ + + self._viewed = viewed + + @property + def signed(self): + """Gets the signed of this Signer. # noqa: E501 + + + :return: The signed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._signed + + @signed.setter + def signed(self, signed): + """Sets the signed of this Signer. + + + :param signed: The signed of this Signer. # noqa: E501 + :type: bool + """ + + self._signed = signed + + @property + def downloaded(self): + """Gets the downloaded of this Signer. # noqa: E501 + + + :return: The downloaded of this Signer. # noqa: E501 + :rtype: bool + """ + return self._downloaded + + @downloaded.setter + def downloaded(self, downloaded): + """Sets the downloaded of this Signer. + + + :param downloaded: The downloaded of this Signer. # noqa: E501 + :type: bool + """ + + self._downloaded = downloaded + + @property + def signed_on(self): + """Gets the signed_on of this Signer. # noqa: E501 + + + :return: The signed_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._signed_on + + @signed_on.setter + def signed_on(self, signed_on): + """Sets the signed_on of this Signer. + + + :param signed_on: The signed_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._signed_on = signed_on + + @property + def needs_to_sign(self): + """Gets the needs_to_sign of this Signer. # noqa: E501 + + + :return: The needs_to_sign of this Signer. # noqa: E501 + :rtype: bool + """ + return self._needs_to_sign + + @needs_to_sign.setter + def needs_to_sign(self, needs_to_sign): + """Sets the needs_to_sign of this Signer. + + + :param needs_to_sign: The needs_to_sign of this Signer. # noqa: E501 + :type: bool + """ + + self._needs_to_sign = needs_to_sign + + @property + def approve_only(self): + """Gets the approve_only of this Signer. # noqa: E501 + + + :return: The approve_only of this Signer. # noqa: E501 + :rtype: bool + """ + return self._approve_only + + @approve_only.setter + def approve_only(self, approve_only): + """Sets the approve_only of this Signer. + + + :param approve_only: The approve_only of this Signer. # noqa: E501 + :type: bool + """ + + self._approve_only = approve_only + + @property + def notify_only(self): + """Gets the notify_only of this Signer. # noqa: E501 + + + :return: The notify_only of this Signer. # noqa: E501 + :rtype: bool + """ + return self._notify_only + + @notify_only.setter + def notify_only(self, notify_only): + """Sets the notify_only of this Signer. + + + :param notify_only: The notify_only of this Signer. # noqa: E501 + :type: bool + """ + + self._notify_only = notify_only + + @property + def in_person(self): + """Gets the in_person of this Signer. # noqa: E501 + + + :return: The in_person of this Signer. # noqa: E501 + :rtype: bool + """ + return self._in_person + + @in_person.setter + def in_person(self, in_person): + """Sets the in_person of this Signer. + + + :param in_person: The in_person of this Signer. # noqa: E501 + :type: bool + """ + + self._in_person = in_person + + @property + def order(self): + """Gets the order of this Signer. # noqa: E501 + + + :return: The order of this Signer. # noqa: E501 + :rtype: int + """ + return self._order + + @order.setter + def order(self, order): + """Sets the order of this Signer. + + + :param order: The order of this Signer. # noqa: E501 + :type: int + """ + if order is not None and order > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 + if order is not None and order < 0: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 + + self._order = order + + @property + def language(self): + """Gets the language of this Signer. # noqa: E501 + + + :return: The language of this Signer. # noqa: E501 + :rtype: str + """ + return self._language + + @language.setter + def language(self, language): + """Sets the language of this Signer. + + + :param language: The language of this Signer. # noqa: E501 + :type: str + """ + allowed_values = ["en", "en-gb", "nl", "fr", "de", "he", "da", "fi", "hu", "it", "no", "pl", "pt", "es", "sv", "ru"] # noqa: E501 + if language not in allowed_values: + raise ValueError( + "Invalid value for `language` ({0}), must be one of {1}" # noqa: E501 + .format(language, allowed_values) + ) + + self._language = language + + @property + def force_language(self): + """Gets the force_language of this Signer. # noqa: E501 + + + :return: The force_language of this Signer. # noqa: E501 + :rtype: bool + """ + return self._force_language + + @force_language.setter + def force_language(self, force_language): + """Sets the force_language of this Signer. + + + :param force_language: The force_language of this Signer. # noqa: E501 + :type: bool + """ + + self._force_language = force_language + + @property + def emailed(self): + """Gets the emailed of this Signer. # noqa: E501 + + + :return: The emailed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._emailed + + @emailed.setter + def emailed(self, emailed): + """Sets the emailed of this Signer. + + + :param emailed: The emailed of this Signer. # noqa: E501 + :type: bool + """ + + self._emailed = emailed + + @property + def verify_phone_number(self): + """Gets the verify_phone_number of this Signer. # noqa: E501 + + + :return: The verify_phone_number of this Signer. # noqa: E501 + :rtype: str + """ + return self._verify_phone_number + + @verify_phone_number.setter + def verify_phone_number(self, verify_phone_number): + """Sets the verify_phone_number of this Signer. + + + :param verify_phone_number: The verify_phone_number of this Signer. # noqa: E501 + :type: str + """ + if verify_phone_number is not None and len(verify_phone_number) > 255: + raise ValueError("Invalid value for `verify_phone_number`, length must be less than or equal to `255`") # noqa: E501 + + self._verify_phone_number = verify_phone_number + + @property + def verify_bank_account(self): + """Gets the verify_bank_account of this Signer. # noqa: E501 + + + :return: The verify_bank_account of this Signer. # noqa: E501 + :rtype: str + """ + return self._verify_bank_account + + @verify_bank_account.setter + def verify_bank_account(self, verify_bank_account): + """Sets the verify_bank_account of this Signer. + + + :param verify_bank_account: The verify_bank_account of this Signer. # noqa: E501 + :type: str + """ + if verify_bank_account is not None and len(verify_bank_account) > 255: + raise ValueError("Invalid value for `verify_bank_account`, length must be less than or equal to `255`") # noqa: E501 + + self._verify_bank_account = verify_bank_account + + @property + def declined(self): + """Gets the declined of this Signer. # noqa: E501 + + + :return: The declined of this Signer. # noqa: E501 + :rtype: bool + """ + return self._declined + + @declined.setter + def declined(self, declined): + """Sets the declined of this Signer. + + + :param declined: The declined of this Signer. # noqa: E501 + :type: bool + """ + + self._declined = declined + + @property + def declined_on(self): + """Gets the declined_on of this Signer. # noqa: E501 + + + :return: The declined_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._declined_on + + @declined_on.setter + def declined_on(self, declined_on): + """Sets the declined_on of this Signer. + + + :param declined_on: The declined_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._declined_on = declined_on + + @property + def forwarded(self): + """Gets the forwarded of this Signer. # noqa: E501 + + + :return: The forwarded of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded + + @forwarded.setter + def forwarded(self, forwarded): + """Sets the forwarded of this Signer. + + + :param forwarded: The forwarded of this Signer. # noqa: E501 + :type: str + """ + + self._forwarded = forwarded + + @property + def forwarded_on(self): + """Gets the forwarded_on of this Signer. # noqa: E501 + + + :return: The forwarded_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._forwarded_on + + @forwarded_on.setter + def forwarded_on(self, forwarded_on): + """Sets the forwarded_on of this Signer. + + + :param forwarded_on: The forwarded_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._forwarded_on = forwarded_on + + @property + def forwarded_to_email(self): + """Gets the forwarded_to_email of this Signer. # noqa: E501 + + + :return: The forwarded_to_email of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded_to_email + + @forwarded_to_email.setter + def forwarded_to_email(self, forwarded_to_email): + """Sets the forwarded_to_email of this Signer. + + + :param forwarded_to_email: The forwarded_to_email of this Signer. # noqa: E501 + :type: str + """ + if forwarded_to_email is not None and len(forwarded_to_email) < 1: + raise ValueError("Invalid value for `forwarded_to_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._forwarded_to_email = forwarded_to_email + + @property + def forwarded_reason(self): + """Gets the forwarded_reason of this Signer. # noqa: E501 + + + :return: The forwarded_reason of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded_reason + + @forwarded_reason.setter + def forwarded_reason(self, forwarded_reason): + """Sets the forwarded_reason of this Signer. + + + :param forwarded_reason: The forwarded_reason of this Signer. # noqa: E501 + :type: str + """ + if forwarded_reason is not None and len(forwarded_reason) < 1: + raise ValueError("Invalid value for `forwarded_reason`, length must be greater than or equal to `1`") # noqa: E501 + + self._forwarded_reason = forwarded_reason + + @property + def message(self): + """Gets the message of this Signer. # noqa: E501 + + + :return: The message of this Signer. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this Signer. + + + :param message: The message of this Signer. # noqa: E501 + :type: str + """ + if message is not None and len(message) < 1: + raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 + + self._message = message + + @property + def embed_url_user_id(self): + """Gets the embed_url_user_id of this Signer. # noqa: E501 + + + :return: The embed_url_user_id of this Signer. # noqa: E501 + :rtype: str + """ + return self._embed_url_user_id + + @embed_url_user_id.setter + def embed_url_user_id(self, embed_url_user_id): + """Sets the embed_url_user_id of this Signer. + + + :param embed_url_user_id: The embed_url_user_id of this Signer. # noqa: E501 + :type: str + """ + if embed_url_user_id is not None and len(embed_url_user_id) > 255: + raise ValueError("Invalid value for `embed_url_user_id`, length must be less than or equal to `255`") # noqa: E501 + + self._embed_url_user_id = embed_url_user_id + + @property + def inputs(self): + """Gets the inputs of this Signer. # noqa: E501 + + + :return: The inputs of this Signer. # noqa: E501 + :rtype: list[SignerInputs] + """ + return self._inputs + + @inputs.setter + def inputs(self, inputs): + """Sets the inputs of this Signer. + + + :param inputs: The inputs of this Signer. # noqa: E501 + :type: list[SignerInputs] + """ + + self._inputs = inputs + + @property + def embed_url(self): + """Gets the embed_url of this Signer. # noqa: E501 + + + :return: The embed_url of this Signer. # noqa: E501 + :rtype: str + """ + return self._embed_url + + @embed_url.setter + def embed_url(self, embed_url): + """Sets the embed_url of this Signer. + + + :param embed_url: The embed_url of this Signer. # noqa: E501 + :type: str + """ + if embed_url is not None and len(embed_url) < 1: + raise ValueError("Invalid value for `embed_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._embed_url = embed_url + + @property + def attachments(self): + """Gets the attachments of this Signer. # noqa: E501 + + + :return: The attachments of this Signer. # noqa: E501 + :rtype: list[SignerAttachment] + """ + return self._attachments + + @attachments.setter + def attachments(self, attachments): + """Sets the attachments of this Signer. + + + :param attachments: The attachments of this Signer. # noqa: E501 + :type: list[SignerAttachment] + """ + + self._attachments = attachments + + @property + def redirect_url(self): + """Gets the redirect_url of this Signer. # noqa: E501 + + + :return: The redirect_url of this Signer. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this Signer. + + + :param redirect_url: The redirect_url of this Signer. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def after_document(self): + """Gets the after_document of this Signer. # noqa: E501 + + + :return: The after_document of this Signer. # noqa: E501 + :rtype: str + """ + return self._after_document + + @after_document.setter + def after_document(self, after_document): + """Sets the after_document of this Signer. + + + :param after_document: The after_document of this Signer. # noqa: E501 + :type: str + """ + + self._after_document = after_document + + @property + def integrations(self): + """Gets the integrations of this Signer. # noqa: E501 + + + :return: The integrations of this Signer. # noqa: E501 + :rtype: list[InlineDocumentSignerIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this Signer. + + + :param integrations: The integrations of this Signer. # noqa: E501 + :type: list[InlineDocumentSignerIntegrationData] + """ + + self._integrations = integrations + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Signer): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/signer_attachment.py b/signrequest_python_client/models/signer_attachment.py new file mode 100644 index 0000000..4a74c9a --- /dev/null +++ b/signrequest_python_client/models/signer_attachment.py @@ -0,0 +1,198 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 + + +class SignerAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'name': 'str', + 'file': 'str', + 'for_attachment': 'RequiredAttachment' + } + + attribute_map = { + 'uuid': 'uuid', + 'name': 'name', + 'file': 'file', + 'for_attachment': 'for_attachment' + } + + def __init__(self, uuid=None, name=None, file=None, for_attachment=None): # noqa: E501 + """SignerAttachment - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._name = None + self._file = None + self._for_attachment = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + if file is not None: + self.file = file + if for_attachment is not None: + self.for_attachment = for_attachment + + @property + def uuid(self): + """Gets the uuid of this SignerAttachment. # noqa: E501 + + + :return: The uuid of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignerAttachment. + + + :param uuid: The uuid of this SignerAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this SignerAttachment. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this SignerAttachment. + + Defaults to filename # noqa: E501 + + :param name: The name of this SignerAttachment. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def file(self): + """Gets the file of this SignerAttachment. # noqa: E501 + + + :return: The file of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this SignerAttachment. + + + :param file: The file of this SignerAttachment. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def for_attachment(self): + """Gets the for_attachment of this SignerAttachment. # noqa: E501 + + + :return: The for_attachment of this SignerAttachment. # noqa: E501 + :rtype: RequiredAttachment + """ + return self._for_attachment + + @for_attachment.setter + def for_attachment(self, for_attachment): + """Sets the for_attachment of this SignerAttachment. + + + :param for_attachment: The for_attachment of this SignerAttachment. # noqa: E501 + :type: RequiredAttachment + """ + + self._for_attachment = for_attachment + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignerAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/signer_inputs.py b/signrequest_python_client/models/signer_inputs.py new file mode 100644 index 0000000..efbe89c --- /dev/null +++ b/signrequest_python_client/models/signer_inputs.py @@ -0,0 +1,279 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class SignerInputs(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'type': 'str', + 'page_index': 'int', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date', + 'external_id': 'str', + 'placeholder_uuid': 'str' + } + + attribute_map = { + 'type': 'type', + 'page_index': 'page_index', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value', + 'external_id': 'external_id', + 'placeholder_uuid': 'placeholder_uuid' + } + + def __init__(self, type=None, page_index=None, text=None, checkbox_value=None, date_value=None, external_id=None, placeholder_uuid=None): # noqa: E501 + """SignerInputs - a model defined in Swagger""" # noqa: E501 + + self._type = None + self._page_index = None + self._text = None + self._checkbox_value = None + self._date_value = None + self._external_id = None + self._placeholder_uuid = None + self.discriminator = None + + if type is not None: + self.type = type + self.page_index = page_index + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + if external_id is not None: + self.external_id = external_id + if placeholder_uuid is not None: + self.placeholder_uuid = placeholder_uuid + + @property + def type(self): + """Gets the type of this SignerInputs. # noqa: E501 + + + :return: The type of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._type + + @type.setter + def type(self, type): + """Sets the type of this SignerInputs. + + + :param type: The type of this SignerInputs. # noqa: E501 + :type: str + """ + allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 + if type not in allowed_values: + raise ValueError( + "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 + .format(type, allowed_values) + ) + + self._type = type + + @property + def page_index(self): + """Gets the page_index of this SignerInputs. # noqa: E501 + + + :return: The page_index of this SignerInputs. # noqa: E501 + :rtype: int + """ + return self._page_index + + @page_index.setter + def page_index(self, page_index): + """Sets the page_index of this SignerInputs. + + + :param page_index: The page_index of this SignerInputs. # noqa: E501 + :type: int + """ + if page_index is None: + raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 + + self._page_index = page_index + + @property + def text(self): + """Gets the text of this SignerInputs. # noqa: E501 + + + :return: The text of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this SignerInputs. + + + :param text: The text of this SignerInputs. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this SignerInputs. # noqa: E501 + + + :return: The checkbox_value of this SignerInputs. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this SignerInputs. + + + :param checkbox_value: The checkbox_value of this SignerInputs. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this SignerInputs. # noqa: E501 + + + :return: The date_value of this SignerInputs. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this SignerInputs. + + + :param date_value: The date_value of this SignerInputs. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this SignerInputs. # noqa: E501 + + + :return: The external_id of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this SignerInputs. + + + :param external_id: The external_id of this SignerInputs. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def placeholder_uuid(self): + """Gets the placeholder_uuid of this SignerInputs. # noqa: E501 + + + :return: The placeholder_uuid of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._placeholder_uuid + + @placeholder_uuid.setter + def placeholder_uuid(self, placeholder_uuid): + """Sets the placeholder_uuid of this SignerInputs. + + + :param placeholder_uuid: The placeholder_uuid of this SignerInputs. # noqa: E501 + :type: str + """ + if placeholder_uuid is not None and len(placeholder_uuid) > 36: + raise ValueError("Invalid value for `placeholder_uuid`, length must be less than or equal to `36`") # noqa: E501 + + self._placeholder_uuid = placeholder_uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignerInputs): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/signing_log.py b/signrequest_python_client/models/signing_log.py new file mode 100644 index 0000000..6300f28 --- /dev/null +++ b/signrequest_python_client/models/signing_log.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class SigningLog(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'pdf': 'str', + 'security_hash': 'str' + } + + attribute_map = { + 'pdf': 'pdf', + 'security_hash': 'security_hash' + } + + def __init__(self, pdf=None, security_hash=None): # noqa: E501 + """SigningLog - a model defined in Swagger""" # noqa: E501 + + self._pdf = None + self._security_hash = None + self.discriminator = None + + if pdf is not None: + self.pdf = pdf + if security_hash is not None: + self.security_hash = security_hash + + @property + def pdf(self): + """Gets the pdf of this SigningLog. # noqa: E501 + + Temporary URL to signing log, expires in five minutes # noqa: E501 + + :return: The pdf of this SigningLog. # noqa: E501 + :rtype: str + """ + return self._pdf + + @pdf.setter + def pdf(self, pdf): + """Sets the pdf of this SigningLog. + + Temporary URL to signing log, expires in five minutes # noqa: E501 + + :param pdf: The pdf of this SigningLog. # noqa: E501 + :type: str + """ + + self._pdf = pdf + + @property + def security_hash(self): + """Gets the security_hash of this SigningLog. # noqa: E501 + + SHA256 hash of PDF contents # noqa: E501 + + :return: The security_hash of this SigningLog. # noqa: E501 + :rtype: str + """ + return self._security_hash + + @security_hash.setter + def security_hash(self, security_hash): + """Sets the security_hash of this SigningLog. + + SHA256 hash of PDF contents # noqa: E501 + + :param security_hash: The security_hash of this SigningLog. # noqa: E501 + :type: str + """ + if security_hash is not None and len(security_hash) < 1: + raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 + + self._security_hash = security_hash + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SigningLog): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/team.py b/signrequest_python_client/models/team.py new file mode 100644 index 0000000..3f3fcb7 --- /dev/null +++ b/signrequest_python_client/models/team.py @@ -0,0 +1,312 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.inline_team_member import InlineTeamMember # noqa: F401,E501 + + +class Team(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'subdomain': 'str', + 'url': 'str', + 'logo': 'str', + 'phone': 'str', + 'primary_color': 'str', + 'events_callback_url': 'str', + 'members': 'list[InlineTeamMember]' + } + + attribute_map = { + 'name': 'name', + 'subdomain': 'subdomain', + 'url': 'url', + 'logo': 'logo', + 'phone': 'phone', + 'primary_color': 'primary_color', + 'events_callback_url': 'events_callback_url', + 'members': 'members' + } + + def __init__(self, name=None, subdomain=None, url=None, logo=None, phone=None, primary_color=None, events_callback_url=None, members=None): # noqa: E501 + """Team - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._subdomain = None + self._url = None + self._logo = None + self._phone = None + self._primary_color = None + self._events_callback_url = None + self._members = None + self.discriminator = None + + self.name = name + self.subdomain = subdomain + if url is not None: + self.url = url + if logo is not None: + self.logo = logo + if phone is not None: + self.phone = phone + if primary_color is not None: + self.primary_color = primary_color + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if members is not None: + self.members = members + + @property + def name(self): + """Gets the name of this Team. # noqa: E501 + + + :return: The name of this Team. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Team. + + + :param name: The name of this Team. # noqa: E501 + :type: str + """ + if name is None: + raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 + if name is not None and len(name) > 100: + raise ValueError("Invalid value for `name`, length must be less than or equal to `100`") # noqa: E501 + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def subdomain(self): + """Gets the subdomain of this Team. # noqa: E501 + + + :return: The subdomain of this Team. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this Team. + + + :param subdomain: The subdomain of this Team. # noqa: E501 + :type: str + """ + if subdomain is None: + raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 + if subdomain is not None and len(subdomain) > 100: + raise ValueError("Invalid value for `subdomain`, length must be less than or equal to `100`") # noqa: E501 + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + + self._subdomain = subdomain + + @property + def url(self): + """Gets the url of this Team. # noqa: E501 + + + :return: The url of this Team. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Team. + + + :param url: The url of this Team. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def logo(self): + """Gets the logo of this Team. # noqa: E501 + + + :return: The logo of this Team. # noqa: E501 + :rtype: str + """ + return self._logo + + @logo.setter + def logo(self, logo): + """Sets the logo of this Team. + + + :param logo: The logo of this Team. # noqa: E501 + :type: str + """ + + self._logo = logo + + @property + def phone(self): + """Gets the phone of this Team. # noqa: E501 + + + :return: The phone of this Team. # noqa: E501 + :rtype: str + """ + return self._phone + + @phone.setter + def phone(self, phone): + """Sets the phone of this Team. + + + :param phone: The phone of this Team. # noqa: E501 + :type: str + """ + if phone is not None and len(phone) > 100: + raise ValueError("Invalid value for `phone`, length must be less than or equal to `100`") # noqa: E501 + + self._phone = phone + + @property + def primary_color(self): + """Gets the primary_color of this Team. # noqa: E501 + + + :return: The primary_color of this Team. # noqa: E501 + :rtype: str + """ + return self._primary_color + + @primary_color.setter + def primary_color(self, primary_color): + """Sets the primary_color of this Team. + + + :param primary_color: The primary_color of this Team. # noqa: E501 + :type: str + """ + if primary_color is not None and len(primary_color) > 100: + raise ValueError("Invalid value for `primary_color`, length must be less than or equal to `100`") # noqa: E501 + + self._primary_color = primary_color + + @property + def events_callback_url(self): + """Gets the events_callback_url of this Team. # noqa: E501 + + + :return: The events_callback_url of this Team. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this Team. + + + :param events_callback_url: The events_callback_url of this Team. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def members(self): + """Gets the members of this Team. # noqa: E501 + + + :return: The members of this Team. # noqa: E501 + :rtype: list[InlineTeamMember] + """ + return self._members + + @members.setter + def members(self, members): + """Sets the members of this Team. + + + :param members: The members of this Team. # noqa: E501 + :type: list[InlineTeamMember] + """ + + self._members = members + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Team): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/team_member.py b/signrequest_python_client/models/team_member.py new file mode 100644 index 0000000..8f66a65 --- /dev/null +++ b/signrequest_python_client/models/team_member.py @@ -0,0 +1,246 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.user import User # noqa: F401,E501 + + +class TeamMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'url': 'str', + 'user': 'User', + 'is_admin': 'bool', + 'is_active': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'uuid': 'uuid', + 'url': 'url', + 'user': 'user', + 'is_admin': 'is_admin', + 'is_active': 'is_active', + 'is_owner': 'is_owner' + } + + def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 + """TeamMember - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._url = None + self._user = None + self._is_admin = None + self._is_active = None + self._is_owner = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if user is not None: + self.user = user + if is_admin is not None: + self.is_admin = is_admin + if is_active is not None: + self.is_active = is_active + if is_owner is not None: + self.is_owner = is_owner + + @property + def uuid(self): + """Gets the uuid of this TeamMember. # noqa: E501 + + + :return: The uuid of this TeamMember. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this TeamMember. + + + :param uuid: The uuid of this TeamMember. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this TeamMember. # noqa: E501 + + + :return: The url of this TeamMember. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this TeamMember. + + + :param url: The url of this TeamMember. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def user(self): + """Gets the user of this TeamMember. # noqa: E501 + + + :return: The user of this TeamMember. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this TeamMember. + + + :param user: The user of this TeamMember. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def is_admin(self): + """Gets the is_admin of this TeamMember. # noqa: E501 + + + :return: The is_admin of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this TeamMember. + + + :param is_admin: The is_admin of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_active(self): + """Gets the is_active of this TeamMember. # noqa: E501 + + + :return: The is_active of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_active + + @is_active.setter + def is_active(self, is_active): + """Sets the is_active of this TeamMember. + + + :param is_active: The is_active of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_active = is_active + + @property + def is_owner(self): + """Gets the is_owner of this TeamMember. # noqa: E501 + + + :return: The is_owner of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this TeamMember. + + + :param is_owner: The is_owner of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, TeamMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/template.py b/signrequest_python_client/models/template.py new file mode 100644 index 0000000..ae6a84d --- /dev/null +++ b/signrequest_python_client/models/template.py @@ -0,0 +1,259 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf # noqa: F401,E501 +from signrequest_python_client.models.user import User # noqa: F401,E501 + + +class Template(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'name': 'str', + 'uuid': 'str', + 'user': 'User', + 'who': 'str', + 'signers': 'list[DocumentSignerTemplateConf]' + } + + attribute_map = { + 'url': 'url', + 'name': 'name', + 'uuid': 'uuid', + 'user': 'user', + 'who': 'who', + 'signers': 'signers' + } + + def __init__(self, url=None, name=None, uuid=None, user=None, who=None, signers=None): # noqa: E501 + """Template - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._name = None + self._uuid = None + self._user = None + self._who = None + self._signers = None + self.discriminator = None + + if url is not None: + self.url = url + if name is not None: + self.name = name + if uuid is not None: + self.uuid = uuid + if user is not None: + self.user = user + if who is not None: + self.who = who + if signers is not None: + self.signers = signers + + @property + def url(self): + """Gets the url of this Template. # noqa: E501 + + + :return: The url of this Template. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Template. + + + :param url: The url of this Template. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def name(self): + """Gets the name of this Template. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this Template. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Template. + + Defaults to filename # noqa: E501 + + :param name: The name of this Template. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def uuid(self): + """Gets the uuid of this Template. # noqa: E501 + + + :return: The uuid of this Template. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Template. + + + :param uuid: The uuid of this Template. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def user(self): + """Gets the user of this Template. # noqa: E501 + + + :return: The user of this Template. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this Template. + + + :param user: The user of this Template. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def who(self): + """Gets the who of this Template. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this Template. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this Template. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this Template. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def signers(self): + """Gets the signers of this Template. # noqa: E501 + + + :return: The signers of this Template. # noqa: E501 + :rtype: list[DocumentSignerTemplateConf] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this Template. + + + :param signers: The signers of this Template. # noqa: E501 + :type: list[DocumentSignerTemplateConf] + """ + + self._signers = signers + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Template): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/user.py b/signrequest_python_client/models/user.py new file mode 100644 index 0000000..3242acd --- /dev/null +++ b/signrequest_python_client/models/user.py @@ -0,0 +1,201 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class User(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'first_name': 'str', + 'last_name': 'str', + 'display_name': 'str' + } + + attribute_map = { + 'email': 'email', + 'first_name': 'first_name', + 'last_name': 'last_name', + 'display_name': 'display_name' + } + + def __init__(self, email=None, first_name=None, last_name=None, display_name=None): # noqa: E501 + """User - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._first_name = None + self._last_name = None + self._display_name = None + self.discriminator = None + + self.email = email + if first_name is not None: + self.first_name = first_name + if last_name is not None: + self.last_name = last_name + if display_name is not None: + self.display_name = display_name + + @property + def email(self): + """Gets the email of this User. # noqa: E501 + + + :return: The email of this User. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this User. + + + :param email: The email of this User. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) > 254: + raise ValueError("Invalid value for `email`, length must be less than or equal to `254`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def first_name(self): + """Gets the first_name of this User. # noqa: E501 + + + :return: The first_name of this User. # noqa: E501 + :rtype: str + """ + return self._first_name + + @first_name.setter + def first_name(self, first_name): + """Sets the first_name of this User. + + + :param first_name: The first_name of this User. # noqa: E501 + :type: str + """ + if first_name is not None and len(first_name) > 255: + raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 + + self._first_name = first_name + + @property + def last_name(self): + """Gets the last_name of this User. # noqa: E501 + + + :return: The last_name of this User. # noqa: E501 + :rtype: str + """ + return self._last_name + + @last_name.setter + def last_name(self, last_name): + """Sets the last_name of this User. + + + :param last_name: The last_name of this User. # noqa: E501 + :type: str + """ + if last_name is not None and len(last_name) > 255: + raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 + + self._last_name = last_name + + @property + def display_name(self): + """Gets the display_name of this User. # noqa: E501 + + + :return: The display_name of this User. # noqa: E501 + :rtype: str + """ + return self._display_name + + @display_name.setter + def display_name(self, display_name): + """Sets the display_name of this User. + + + :param display_name: The display_name of this User. # noqa: E501 + :type: str + """ + if display_name is not None and len(display_name) < 1: + raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 + + self._display_name = display_name + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, User): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/webhook_subscription.py b/signrequest_python_client/models/webhook_subscription.py new file mode 100644 index 0000000..209cbdd --- /dev/null +++ b/signrequest_python_client/models/webhook_subscription.py @@ -0,0 +1,292 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class WebhookSubscription(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'name': 'str', + 'event_type': 'str', + 'callback_url': 'str', + 'integration': 'str', + 'created': 'datetime' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'name': 'name', + 'event_type': 'event_type', + 'callback_url': 'callback_url', + 'integration': 'integration', + 'created': 'created' + } + + def __init__(self, url=None, uuid=None, name=None, event_type=None, callback_url=None, integration=None, created=None): # noqa: E501 + """WebhookSubscription - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._name = None + self._event_type = None + self._callback_url = None + self._integration = None + self._created = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + self.event_type = event_type + self.callback_url = callback_url + if integration is not None: + self.integration = integration + if created is not None: + self.created = created + + @property + def url(self): + """Gets the url of this WebhookSubscription. # noqa: E501 + + + :return: The url of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this WebhookSubscription. + + + :param url: The url of this WebhookSubscription. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this WebhookSubscription. # noqa: E501 + + + :return: The uuid of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this WebhookSubscription. + + + :param uuid: The uuid of this WebhookSubscription. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this WebhookSubscription. # noqa: E501 + + Optional name to easily identify what webhook is used for # noqa: E501 + + :return: The name of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this WebhookSubscription. + + Optional name to easily identify what webhook is used for # noqa: E501 + + :param name: The name of this WebhookSubscription. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def event_type(self): + """Gets the event_type of this WebhookSubscription. # noqa: E501 + + + :return: The event_type of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._event_type + + @event_type.setter + def event_type(self, event_type): + """Sets the event_type of this WebhookSubscription. + + + :param event_type: The event_type of this WebhookSubscription. # noqa: E501 + :type: str + """ + if event_type is None: + raise ValueError("Invalid value for `event_type`, must not be `None`") # noqa: E501 + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + if event_type not in allowed_values: + raise ValueError( + "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 + .format(event_type, allowed_values) + ) + + self._event_type = event_type + + @property + def callback_url(self): + """Gets the callback_url of this WebhookSubscription. # noqa: E501 + + + :return: The callback_url of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._callback_url + + @callback_url.setter + def callback_url(self, callback_url): + """Sets the callback_url of this WebhookSubscription. + + + :param callback_url: The callback_url of this WebhookSubscription. # noqa: E501 + :type: str + """ + if callback_url is None: + raise ValueError("Invalid value for `callback_url`, must not be `None`") # noqa: E501 + if callback_url is not None and len(callback_url) > 2100: + raise ValueError("Invalid value for `callback_url`, length must be less than or equal to `2100`") # noqa: E501 + if callback_url is not None and len(callback_url) < 1: + raise ValueError("Invalid value for `callback_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._callback_url = callback_url + + @property + def integration(self): + """Gets the integration of this WebhookSubscription. # noqa: E501 + + + :return: The integration of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this WebhookSubscription. + + + :param integration: The integration of this WebhookSubscription. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def created(self): + """Gets the created of this WebhookSubscription. # noqa: E501 + + + :return: The created of this WebhookSubscription. # noqa: E501 + :rtype: datetime + """ + return self._created + + @created.setter + def created(self, created): + """Sets the created of this WebhookSubscription. + + + :param created: The created of this WebhookSubscription. # noqa: E501 + :type: datetime + """ + + self._created = created + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, WebhookSubscription): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/rest.py b/signrequest_python_client/rest.py new file mode 100644 index 0000000..4603c91 --- /dev/null +++ b/signrequest_python_client/rest.py @@ -0,0 +1,323 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import io +import json +import logging +import re +import ssl + +import certifi +# python 2 and python 3 compatibility library +import six +from six.moves.urllib.parse import urlencode + +try: + import urllib3 +except ImportError: + raise ImportError('Swagger python client requires urllib3.') + + +logger = logging.getLogger(__name__) + + +class RESTResponse(io.IOBase): + + def __init__(self, resp): + self.urllib3_response = resp + self.status = resp.status + self.reason = resp.reason + self.data = resp.data + + def getheaders(self): + """Returns a dictionary of the response headers.""" + return self.urllib3_response.getheaders() + + def getheader(self, name, default=None): + """Returns a given response header.""" + return self.urllib3_response.getheader(name, default) + + +class RESTClientObject(object): + + def __init__(self, configuration, pools_size=4, maxsize=None): + # urllib3.PoolManager will pass all kw parameters to connectionpool + # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75 # noqa: E501 + # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680 # noqa: E501 + # maxsize is the number of requests to host that are allowed in parallel # noqa: E501 + # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html # noqa: E501 + + # cert_reqs + if configuration.verify_ssl: + cert_reqs = ssl.CERT_REQUIRED + else: + cert_reqs = ssl.CERT_NONE + + # ca_certs + if configuration.ssl_ca_cert: + ca_certs = configuration.ssl_ca_cert + else: + # if not set certificate file, use Mozilla's root certificates. + ca_certs = certifi.where() + + addition_pool_args = {} + if configuration.assert_hostname is not None: + addition_pool_args['assert_hostname'] = configuration.assert_hostname # noqa: E501 + + if maxsize is None: + if configuration.connection_pool_maxsize is not None: + maxsize = configuration.connection_pool_maxsize + else: + maxsize = 4 + + # https pool manager + if configuration.proxy: + self.pool_manager = urllib3.ProxyManager( + num_pools=pools_size, + maxsize=maxsize, + cert_reqs=cert_reqs, + ca_certs=ca_certs, + cert_file=configuration.cert_file, + key_file=configuration.key_file, + proxy_url=configuration.proxy, + **addition_pool_args + ) + else: + self.pool_manager = urllib3.PoolManager( + num_pools=pools_size, + maxsize=maxsize, + cert_reqs=cert_reqs, + ca_certs=ca_certs, + cert_file=configuration.cert_file, + key_file=configuration.key_file, + **addition_pool_args + ) + + def request(self, method, url, query_params=None, headers=None, + body=None, post_params=None, _preload_content=True, + _request_timeout=None): + """Perform requests. + + :param method: http request method + :param url: http request url + :param query_params: query parameters in the url + :param headers: http request headers + :param body: request json body, for `application/json` + :param post_params: request post parameters, + `application/x-www-form-urlencoded` + and `multipart/form-data` + :param _preload_content: if False, the urllib3.HTTPResponse object will + be returned without reading/decoding response + data. Default is True. + :param _request_timeout: timeout setting for this request. If one + number provided, it will be total request + timeout. It can also be a pair (tuple) of + (connection, read) timeouts. + """ + method = method.upper() + assert method in ['GET', 'HEAD', 'DELETE', 'POST', 'PUT', + 'PATCH', 'OPTIONS'] + + if post_params and body: + raise ValueError( + "body parameter cannot be used with post_params parameter." + ) + + post_params = post_params or {} + headers = headers or {} + + timeout = None + if _request_timeout: + if isinstance(_request_timeout, (int, ) if six.PY3 else (int, long)): # noqa: E501,F821 + timeout = urllib3.Timeout(total=_request_timeout) + elif (isinstance(_request_timeout, tuple) and + len(_request_timeout) == 2): + timeout = urllib3.Timeout( + connect=_request_timeout[0], read=_request_timeout[1]) + + if 'Content-Type' not in headers: + headers['Content-Type'] = 'application/json' + + try: + # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE` + if method in ['POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE']: + if query_params: + url += '?' + urlencode(query_params) + if re.search('json', headers['Content-Type'], re.IGNORECASE): + request_body = None + if body is not None: + request_body = json.dumps(body) + r = self.pool_manager.request( + method, url, + body=request_body, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + elif headers['Content-Type'] == 'application/x-www-form-urlencoded': # noqa: E501 + r = self.pool_manager.request( + method, url, + fields=post_params, + encode_multipart=False, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + elif headers['Content-Type'] == 'multipart/form-data': + # must del headers['Content-Type'], or the correct + # Content-Type which generated by urllib3 will be + # overwritten. + del headers['Content-Type'] + r = self.pool_manager.request( + method, url, + fields=post_params, + encode_multipart=True, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + # Pass a `string` parameter directly in the body to support + # other content types than Json when `body` argument is + # provided in serialized form + elif isinstance(body, str): + request_body = body + r = self.pool_manager.request( + method, url, + body=request_body, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + else: + # Cannot generate the request from given parameters + msg = """Cannot prepare a request message for provided + arguments. Please check that your arguments match + declared content type.""" + raise ApiException(status=0, reason=msg) + # For `GET`, `HEAD` + else: + r = self.pool_manager.request(method, url, + fields=query_params, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + except urllib3.exceptions.SSLError as e: + msg = "{0}\n{1}".format(type(e).__name__, str(e)) + raise ApiException(status=0, reason=msg) + + if _preload_content: + r = RESTResponse(r) + + # In the python 3, the response.data is bytes. + # we need to decode it to string. + if six.PY3: + r.data = r.data.decode('utf8') + + # log response body + logger.debug("response body: %s", r.data) + + if not 200 <= r.status <= 299: + raise ApiException(http_resp=r) + + return r + + def GET(self, url, headers=None, query_params=None, _preload_content=True, + _request_timeout=None): + return self.request("GET", url, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + query_params=query_params) + + def HEAD(self, url, headers=None, query_params=None, _preload_content=True, + _request_timeout=None): + return self.request("HEAD", url, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + query_params=query_params) + + def OPTIONS(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("OPTIONS", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def DELETE(self, url, headers=None, query_params=None, body=None, + _preload_content=True, _request_timeout=None): + return self.request("DELETE", url, + headers=headers, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def POST(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("POST", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def PUT(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("PUT", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def PATCH(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("PATCH", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + +class ApiException(Exception): + + def __init__(self, status=None, reason=None, http_resp=None): + if http_resp: + self.status = http_resp.status + self.reason = http_resp.reason + self.body = http_resp.data + self.headers = http_resp.getheaders() + else: + self.status = status + self.reason = reason + self.body = None + self.headers = None + + def __str__(self): + """Custom error messages for exception""" + error_message = "({0})\n"\ + "Reason: {1}\n".format(self.status, self.reason) + if self.headers: + error_message += "HTTP response headers: {0}\n".format( + self.headers) + + if self.body: + error_message += "HTTP response body: {0}\n".format(self.body) + + return error_message diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..2702246 --- /dev/null +++ b/test-requirements.txt @@ -0,0 +1,5 @@ +coverage>=4.0.3 +nose>=1.3.7 +pluggy>=0.3.1 +py>=1.4.31 +randomize>=0.13 diff --git a/test/__init__.py b/test/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/test/test_api_tokens_api.py b/test/test_api_tokens_api.py new file mode 100644 index 0000000..56e2f84 --- /dev/null +++ b/test/test_api_tokens_api.py @@ -0,0 +1,62 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.api_tokens_api import ApiTokensApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestApiTokensApi(unittest.TestCase): + """ApiTokensApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.api_tokens_api.ApiTokensApi() # noqa: E501 + + def tearDown(self): + pass + + def test_api_tokens_create(self): + """Test case for api_tokens_create + + Create an API token # noqa: E501 + """ + pass + + def test_api_tokens_delete(self): + """Test case for api_tokens_delete + + Delete an API token # noqa: E501 + """ + pass + + def test_api_tokens_list(self): + """Test case for api_tokens_list + + Retrieve a list of API tokens # noqa: E501 + """ + pass + + def test_api_tokens_read(self): + """Test case for api_tokens_read + + Retrieve an API token # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_auth_token.py b/test/test_auth_token.py new file mode 100644 index 0000000..76c7395 --- /dev/null +++ b/test/test_auth_token.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.auth_token import AuthToken # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestAuthToken(unittest.TestCase): + """AuthToken unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testAuthToken(self): + """Test AuthToken""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.auth_token.AuthToken() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_document.py b/test/test_document.py new file mode 100644 index 0000000..61c6326 --- /dev/null +++ b/test/test_document.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.document import Document # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocument(unittest.TestCase): + """Document unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testDocument(self): + """Test Document""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.document.Document() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_document_attachment.py b/test/test_document_attachment.py new file mode 100644 index 0000000..83d8b5c --- /dev/null +++ b/test/test_document_attachment.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.document_attachment import DocumentAttachment # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentAttachment(unittest.TestCase): + """DocumentAttachment unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testDocumentAttachment(self): + """Test DocumentAttachment""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.document_attachment.DocumentAttachment() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_document_attachments_api.py b/test/test_document_attachments_api.py new file mode 100644 index 0000000..401e06c --- /dev/null +++ b/test/test_document_attachments_api.py @@ -0,0 +1,55 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.document_attachments_api import DocumentAttachmentsApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentAttachmentsApi(unittest.TestCase): + """DocumentAttachmentsApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.document_attachments_api.DocumentAttachmentsApi() # noqa: E501 + + def tearDown(self): + pass + + def test_document_attachments_create(self): + """Test case for document_attachments_create + + Create a Document Attachment # noqa: E501 + """ + pass + + def test_document_attachments_list(self): + """Test case for document_attachments_list + + Retrieve a list of Document Attachments # noqa: E501 + """ + pass + + def test_document_attachments_read(self): + """Test case for document_attachments_read + + Retrieve a Document Attachment # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_document_search.py b/test/test_document_search.py new file mode 100644 index 0000000..4142575 --- /dev/null +++ b/test/test_document_search.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.document_search import DocumentSearch # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentSearch(unittest.TestCase): + """DocumentSearch unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testDocumentSearch(self): + """Test DocumentSearch""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.document_search.DocumentSearch() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_document_signer_template_conf.py b/test/test_document_signer_template_conf.py new file mode 100644 index 0000000..f0378bb --- /dev/null +++ b/test/test_document_signer_template_conf.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentSignerTemplateConf(unittest.TestCase): + """DocumentSignerTemplateConf unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testDocumentSignerTemplateConf(self): + """Test DocumentSignerTemplateConf""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.document_signer_template_conf.DocumentSignerTemplateConf() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_documents_api.py b/test/test_documents_api.py new file mode 100644 index 0000000..4b95501 --- /dev/null +++ b/test/test_documents_api.py @@ -0,0 +1,69 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.documents_api import DocumentsApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentsApi(unittest.TestCase): + """DocumentsApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.documents_api.DocumentsApi() # noqa: E501 + + def tearDown(self): + pass + + def test_documents_create(self): + """Test case for documents_create + + Create a Document # noqa: E501 + """ + pass + + def test_documents_delete(self): + """Test case for documents_delete + + Delete a Document # noqa: E501 + """ + pass + + def test_documents_delete_files(self): + """Test case for documents_delete_files + + Delete a Document's Files # noqa: E501 + """ + pass + + def test_documents_list(self): + """Test case for documents_list + + Retrieve a list of Documents # noqa: E501 + """ + pass + + def test_documents_read(self): + """Test case for documents_read + + Retrieve a Document # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_documents_search_api.py b/test/test_documents_search_api.py new file mode 100644 index 0000000..b283102 --- /dev/null +++ b/test/test_documents_search_api.py @@ -0,0 +1,41 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.documents_search_api import DocumentsSearchApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestDocumentsSearchApi(unittest.TestCase): + """DocumentsSearchApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.documents_search_api.DocumentsSearchApi() # noqa: E501 + + def tearDown(self): + pass + + def test_documents_search_list(self): + """Test case for documents_search_list + + Search documents # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_event.py b/test/test_event.py new file mode 100644 index 0000000..9d16729 --- /dev/null +++ b/test/test_event.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.event import Event # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestEvent(unittest.TestCase): + """Event unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testEvent(self): + """Test Event""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.event.Event() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_events_api.py b/test/test_events_api.py new file mode 100644 index 0000000..7147bf5 --- /dev/null +++ b/test/test_events_api.py @@ -0,0 +1,48 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.events_api import EventsApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestEventsApi(unittest.TestCase): + """EventsApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.events_api.EventsApi() # noqa: E501 + + def tearDown(self): + pass + + def test_events_list(self): + """Test case for events_list + + Retrieve a list of Events # noqa: E501 + """ + pass + + def test_events_read(self): + """Test case for events_read + + Retrieve an Event # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_file_from_sf.py b/test/test_file_from_sf.py new file mode 100644 index 0000000..879f429 --- /dev/null +++ b/test/test_file_from_sf.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestFileFromSf(unittest.TestCase): + """FileFromSf unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testFileFromSf(self): + """Test FileFromSf""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.file_from_sf.FileFromSf() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_document_signer_integration_data.py b/test/test_inline_document_signer_integration_data.py new file mode 100644 index 0000000..33051a4 --- /dev/null +++ b/test/test_inline_document_signer_integration_data.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineDocumentSignerIntegrationData(unittest.TestCase): + """InlineDocumentSignerIntegrationData unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineDocumentSignerIntegrationData(self): + """Test InlineDocumentSignerIntegrationData""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_document_signer_integration_data.InlineDocumentSignerIntegrationData() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_integration_data.py b/test/test_inline_integration_data.py new file mode 100644 index 0000000..3ad27ec --- /dev/null +++ b/test/test_inline_integration_data.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineIntegrationData(unittest.TestCase): + """InlineIntegrationData unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineIntegrationData(self): + """Test InlineIntegrationData""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_integration_data.InlineIntegrationData() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_prefill_tags.py b/test/test_inline_prefill_tags.py new file mode 100644 index 0000000..b21d4ea --- /dev/null +++ b/test/test_inline_prefill_tags.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlinePrefillTags(unittest.TestCase): + """InlinePrefillTags unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlinePrefillTags(self): + """Test InlinePrefillTags""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_prefill_tags.InlinePrefillTags() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200.py b/test/test_inline_response_200.py new file mode 100644 index 0000000..e2c074b --- /dev/null +++ b/test/test_inline_response_200.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200 import InlineResponse200 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse200(unittest.TestCase): + """InlineResponse200 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse200(self): + """Test InlineResponse200""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200.InlineResponse200() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_1.py b/test/test_inline_response_200_1.py new file mode 100644 index 0000000..f7a878d --- /dev/null +++ b/test/test_inline_response_200_1.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_1 import InlineResponse2001 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2001(unittest.TestCase): + """InlineResponse2001 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2001(self): + """Test InlineResponse2001""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_1.InlineResponse2001() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_2.py b/test/test_inline_response_200_2.py new file mode 100644 index 0000000..124fc5c --- /dev/null +++ b/test/test_inline_response_200_2.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_2 import InlineResponse2002 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2002(unittest.TestCase): + """InlineResponse2002 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2002(self): + """Test InlineResponse2002""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_2.InlineResponse2002() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_3.py b/test/test_inline_response_200_3.py new file mode 100644 index 0000000..75a27fc --- /dev/null +++ b/test/test_inline_response_200_3.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_3 import InlineResponse2003 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2003(unittest.TestCase): + """InlineResponse2003 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2003(self): + """Test InlineResponse2003""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_3.InlineResponse2003() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_4.py b/test/test_inline_response_200_4.py new file mode 100644 index 0000000..1722b08 --- /dev/null +++ b/test/test_inline_response_200_4.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_4 import InlineResponse2004 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2004(unittest.TestCase): + """InlineResponse2004 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2004(self): + """Test InlineResponse2004""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_4.InlineResponse2004() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_5.py b/test/test_inline_response_200_5.py new file mode 100644 index 0000000..5e28ab1 --- /dev/null +++ b/test/test_inline_response_200_5.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_5 import InlineResponse2005 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2005(unittest.TestCase): + """InlineResponse2005 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2005(self): + """Test InlineResponse2005""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_5.InlineResponse2005() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_6.py b/test/test_inline_response_200_6.py new file mode 100644 index 0000000..887f01e --- /dev/null +++ b/test/test_inline_response_200_6.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_6 import InlineResponse2006 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2006(unittest.TestCase): + """InlineResponse2006 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2006(self): + """Test InlineResponse2006""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_6.InlineResponse2006() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_7.py b/test/test_inline_response_200_7.py new file mode 100644 index 0000000..bbe1cb6 --- /dev/null +++ b/test/test_inline_response_200_7.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2007(unittest.TestCase): + """InlineResponse2007 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2007(self): + """Test InlineResponse2007""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_7.InlineResponse2007() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_8.py b/test/test_inline_response_200_8.py new file mode 100644 index 0000000..0424a2e --- /dev/null +++ b/test/test_inline_response_200_8.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2008(unittest.TestCase): + """InlineResponse2008 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2008(self): + """Test InlineResponse2008""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_8.InlineResponse2008() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_200_9.py b/test/test_inline_response_200_9.py new file mode 100644 index 0000000..cd08a76 --- /dev/null +++ b/test/test_inline_response_200_9.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2009(unittest.TestCase): + """InlineResponse2009 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2009(self): + """Test InlineResponse2009""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_200_9.InlineResponse2009() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_sign_request.py b/test/test_inline_sign_request.py new file mode 100644 index 0000000..722e0b7 --- /dev/null +++ b/test/test_inline_sign_request.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_sign_request import InlineSignRequest # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineSignRequest(unittest.TestCase): + """InlineSignRequest unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineSignRequest(self): + """Test InlineSignRequest""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_sign_request.InlineSignRequest() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_team.py b/test/test_inline_team.py new file mode 100644 index 0000000..b38f6ef --- /dev/null +++ b/test/test_inline_team.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_team import InlineTeam # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineTeam(unittest.TestCase): + """InlineTeam unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineTeam(self): + """Test InlineTeam""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_team.InlineTeam() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_team_member.py b/test/test_inline_team_member.py new file mode 100644 index 0000000..4bd90f7 --- /dev/null +++ b/test/test_inline_team_member.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_team_member import InlineTeamMember # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineTeamMember(unittest.TestCase): + """InlineTeamMember unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineTeamMember(self): + """Test InlineTeamMember""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_team_member.InlineTeamMember() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_invite_member.py b/test/test_invite_member.py new file mode 100644 index 0000000..e0146e7 --- /dev/null +++ b/test/test_invite_member.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.invite_member import InviteMember # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInviteMember(unittest.TestCase): + """InviteMember unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInviteMember(self): + """Test InviteMember""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.invite_member.InviteMember() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_placeholder.py b/test/test_placeholder.py new file mode 100644 index 0000000..0d527d5 --- /dev/null +++ b/test/test_placeholder.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.placeholder import Placeholder # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestPlaceholder(unittest.TestCase): + """Placeholder unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testPlaceholder(self): + """Test Placeholder""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.placeholder.Placeholder() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_required_attachment.py b/test/test_required_attachment.py new file mode 100644 index 0000000..52f42a0 --- /dev/null +++ b/test/test_required_attachment.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestRequiredAttachment(unittest.TestCase): + """RequiredAttachment unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testRequiredAttachment(self): + """Test RequiredAttachment""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.required_attachment.RequiredAttachment() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_sign_request.py b/test/test_sign_request.py new file mode 100644 index 0000000..a4ad471 --- /dev/null +++ b/test/test_sign_request.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.sign_request import SignRequest # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignRequest(unittest.TestCase): + """SignRequest unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSignRequest(self): + """Test SignRequest""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.sign_request.SignRequest() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_sign_request_quick_create.py b/test/test_sign_request_quick_create.py new file mode 100644 index 0000000..fc7bdd7 --- /dev/null +++ b/test/test_sign_request_quick_create.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.sign_request_quick_create import SignRequestQuickCreate # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignRequestQuickCreate(unittest.TestCase): + """SignRequestQuickCreate unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSignRequestQuickCreate(self): + """Test SignRequestQuickCreate""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.sign_request_quick_create.SignRequestQuickCreate() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signer.py b/test/test_signer.py new file mode 100644 index 0000000..97d0802 --- /dev/null +++ b/test/test_signer.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.signer import Signer # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSigner(unittest.TestCase): + """Signer unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSigner(self): + """Test Signer""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.signer.Signer() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signer_attachment.py b/test/test_signer_attachment.py new file mode 100644 index 0000000..e6fa223 --- /dev/null +++ b/test/test_signer_attachment.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.signer_attachment import SignerAttachment # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignerAttachment(unittest.TestCase): + """SignerAttachment unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSignerAttachment(self): + """Test SignerAttachment""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.signer_attachment.SignerAttachment() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signer_inputs.py b/test/test_signer_inputs.py new file mode 100644 index 0000000..d3b34aa --- /dev/null +++ b/test/test_signer_inputs.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.signer_inputs import SignerInputs # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignerInputs(unittest.TestCase): + """SignerInputs unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSignerInputs(self): + """Test SignerInputs""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.signer_inputs.SignerInputs() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signing_log.py b/test/test_signing_log.py new file mode 100644 index 0000000..1244ecb --- /dev/null +++ b/test/test_signing_log.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.signing_log import SigningLog # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSigningLog(unittest.TestCase): + """SigningLog unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testSigningLog(self): + """Test SigningLog""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.signing_log.SigningLog() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signrequest_quick_create_api.py b/test/test_signrequest_quick_create_api.py new file mode 100644 index 0000000..04083bc --- /dev/null +++ b/test/test_signrequest_quick_create_api.py @@ -0,0 +1,41 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignrequestQuickCreateApi(unittest.TestCase): + """SignrequestQuickCreateApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.signrequest_quick_create_api.SignrequestQuickCreateApi() # noqa: E501 + + def tearDown(self): + pass + + def test_signrequest_quick_create_create(self): + """Test case for signrequest_quick_create_create + + Quick create a SignRequest # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_signrequests_api.py b/test/test_signrequests_api.py new file mode 100644 index 0000000..43e7e5b --- /dev/null +++ b/test/test_signrequests_api.py @@ -0,0 +1,69 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.signrequests_api import SignrequestsApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestSignrequestsApi(unittest.TestCase): + """SignrequestsApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.signrequests_api.SignrequestsApi() # noqa: E501 + + def tearDown(self): + pass + + def test_signrequests_cancel_signrequest(self): + """Test case for signrequests_cancel_signrequest + + Cancel a SignRequest # noqa: E501 + """ + pass + + def test_signrequests_create(self): + """Test case for signrequests_create + + Create a SignRequest # noqa: E501 + """ + pass + + def test_signrequests_list(self): + """Test case for signrequests_list + + Retrieve a list of SignRequests # noqa: E501 + """ + pass + + def test_signrequests_read(self): + """Test case for signrequests_read + + Retrieve a SignRequest # noqa: E501 + """ + pass + + def test_signrequests_resend_signrequest_email(self): + """Test case for signrequests_resend_signrequest_email + + Resend a SignRequest # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_team.py b/test/test_team.py new file mode 100644 index 0000000..b6432b1 --- /dev/null +++ b/test/test_team.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.team import Team # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTeam(unittest.TestCase): + """Team unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testTeam(self): + """Test Team""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.team.Team() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_team_member.py b/test/test_team_member.py new file mode 100644 index 0000000..e809a30 --- /dev/null +++ b/test/test_team_member.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.team_member import TeamMember # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTeamMember(unittest.TestCase): + """TeamMember unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testTeamMember(self): + """Test TeamMember""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.team_member.TeamMember() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_team_members_api.py b/test/test_team_members_api.py new file mode 100644 index 0000000..527d1a2 --- /dev/null +++ b/test/test_team_members_api.py @@ -0,0 +1,48 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.team_members_api import TeamMembersApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTeamMembersApi(unittest.TestCase): + """TeamMembersApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.team_members_api.TeamMembersApi() # noqa: E501 + + def tearDown(self): + pass + + def test_team_members_list(self): + """Test case for team_members_list + + Retrieve a list of Team Members # noqa: E501 + """ + pass + + def test_team_members_read(self): + """Test case for team_members_read + + Retrieve a Team Member # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_teams_api.py b/test/test_teams_api.py new file mode 100644 index 0000000..52bf025 --- /dev/null +++ b/test/test_teams_api.py @@ -0,0 +1,69 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.teams_api import TeamsApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTeamsApi(unittest.TestCase): + """TeamsApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.teams_api.TeamsApi() # noqa: E501 + + def tearDown(self): + pass + + def test_teams_create(self): + """Test case for teams_create + + Create a Team # noqa: E501 + """ + pass + + def test_teams_invite_member(self): + """Test case for teams_invite_member + + Invite a Team Member # noqa: E501 + """ + pass + + def test_teams_list(self): + """Test case for teams_list + + Retrieve a list of Teams # noqa: E501 + """ + pass + + def test_teams_partial_update(self): + """Test case for teams_partial_update + + Update a Team # noqa: E501 + """ + pass + + def test_teams_read(self): + """Test case for teams_read + + Retrieve a Team # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_template.py b/test/test_template.py new file mode 100644 index 0000000..b69cd6c --- /dev/null +++ b/test/test_template.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.template import Template # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTemplate(unittest.TestCase): + """Template unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testTemplate(self): + """Test Template""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.template.Template() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_templates_api.py b/test/test_templates_api.py new file mode 100644 index 0000000..30b448d --- /dev/null +++ b/test/test_templates_api.py @@ -0,0 +1,48 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.templates_api import TemplatesApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestTemplatesApi(unittest.TestCase): + """TemplatesApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.templates_api.TemplatesApi() # noqa: E501 + + def tearDown(self): + pass + + def test_templates_list(self): + """Test case for templates_list + + Retrieve a list of Templates # noqa: E501 + """ + pass + + def test_templates_read(self): + """Test case for templates_read + + Retrieve a Template # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_user.py b/test/test_user.py new file mode 100644 index 0000000..d5e49ae --- /dev/null +++ b/test/test_user.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.user import User # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestUser(unittest.TestCase): + """User unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testUser(self): + """Test User""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.user.User() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_webhook_subscription.py b/test/test_webhook_subscription.py new file mode 100644 index 0000000..0405999 --- /dev/null +++ b/test/test_webhook_subscription.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.webhook_subscription import WebhookSubscription # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestWebhookSubscription(unittest.TestCase): + """WebhookSubscription unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testWebhookSubscription(self): + """Test WebhookSubscription""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.webhook_subscription.WebhookSubscription() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_webhooks_api.py b/test/test_webhooks_api.py new file mode 100644 index 0000000..9a70d1c --- /dev/null +++ b/test/test_webhooks_api.py @@ -0,0 +1,76 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.api.webhooks_api import WebhooksApi # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestWebhooksApi(unittest.TestCase): + """WebhooksApi unit test stubs""" + + def setUp(self): + self.api = signrequest_python_client.api.webhooks_api.WebhooksApi() # noqa: E501 + + def tearDown(self): + pass + + def test_webhooks_create(self): + """Test case for webhooks_create + + Create a Webhook # noqa: E501 + """ + pass + + def test_webhooks_delete(self): + """Test case for webhooks_delete + + Delete a Webhook # noqa: E501 + """ + pass + + def test_webhooks_list(self): + """Test case for webhooks_list + + Retrieve a list of Webhooks # noqa: E501 + """ + pass + + def test_webhooks_partial_update(self): + """Test case for webhooks_partial_update + + Partially update a Webhook # noqa: E501 + """ + pass + + def test_webhooks_read(self): + """Test case for webhooks_read + + Retrieve a Webhook # noqa: E501 + """ + pass + + def test_webhooks_update(self): + """Test case for webhooks_update + + Update a Webhook # noqa: E501 + """ + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..1cf0829 --- /dev/null +++ b/tox.ini @@ -0,0 +1,10 @@ +[tox] +envlist = py27, py3 + +[testenv] +deps=-r{toxinidir}/requirements.txt + -r{toxinidir}/test-requirements.txt + +commands= + nosetests \ + [] \ No newline at end of file From 1e8c5e2e8ce70991a02afdd21a3a8edb1e45e886 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Tue, 16 Oct 2018 20:33:19 +0200 Subject: [PATCH 03/18] Add document search params --- docs/DocumentsSearchApi.md | 22 ++++++++++- .../api/documents_search_api.py | 38 ++++++++++++++++++- 2 files changed, 57 insertions(+), 3 deletions(-) diff --git a/docs/DocumentsSearchApi.md b/docs/DocumentsSearchApi.md index 459f9fa..3671fb8 100644 --- a/docs/DocumentsSearchApi.md +++ b/docs/DocumentsSearchApi.md @@ -8,7 +8,7 @@ Method | HTTP request | Description # **documents_search_list** -> InlineResponse2002 documents_search_list(page=page, limit=limit) +> InlineResponse2002 documents_search_list(page=page, limit=limit, q=q, autocomplete=autocomplete, name=name, subdomain=subdomain, signer_emails=signer_emails, status=status, who=who, format=format, signer_data=signer_data) Search documents @@ -31,10 +31,19 @@ configuration.api_key_prefix['Authorization'] = 'Token' api_instance = signrequest_python_client.DocumentsSearchApi(signrequest_python_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) +q = 'q_example' # str | Normal search query (optional) +autocomplete = 'autocomplete_example' # str | Partial search query (optional) +name = 'name_example' # str | Document name (optional) +subdomain = 'subdomain_example' # str | (optional) +signer_emails = 'signer_emails_example' # str | Email needed to sign/approve (optional) +status = 'status_example' # str | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending (optional) +who = 'who_example' # str | `m`: only me, `mo`: me and others, `o`: only others (optional) +format = 'format_example' # str | Export format, can be `json` (default), `csv`, or `xls` (optional) +signer_data = 8.14 # float | Set to `1` to export with each signer on a separate row (optional) try: # Search documents - api_response = api_instance.documents_search_list(page=page, limit=limit) + api_response = api_instance.documents_search_list(page=page, limit=limit, q=q, autocomplete=autocomplete, name=name, subdomain=subdomain, signer_emails=signer_emails, status=status, who=who, format=format, signer_data=signer_data) pprint(api_response) except ApiException as e: print("Exception when calling DocumentsSearchApi->documents_search_list: %s\n" % e) @@ -46,6 +55,15 @@ Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **page** | **int**| A page number within the paginated result set. | [optional] **limit** | **int**| Number of results to return per page. | [optional] + **q** | **str**| Normal search query | [optional] + **autocomplete** | **str**| Partial search query | [optional] + **name** | **str**| Document name | [optional] + **subdomain** | **str**| | [optional] + **signer_emails** | **str**| Email needed to sign/approve | [optional] + **status** | **str**| `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] + **who** | **str**| `m`: only me, `mo`: me and others, `o`: only others | [optional] + **format** | **str**| Export format, can be `json` (default), `csv`, or `xls` | [optional] + **signer_data** | **float**| Set to `1` to export with each signer on a separate row | [optional] ### Return type diff --git a/signrequest_python_client/api/documents_search_api.py b/signrequest_python_client/api/documents_search_api.py index 86ad8bd..bdcca7b 100644 --- a/signrequest_python_client/api/documents_search_api.py +++ b/signrequest_python_client/api/documents_search_api.py @@ -45,6 +45,15 @@ def documents_search_list(self, **kwargs): # noqa: E501 :param async bool :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. + :param str q: Normal search query + :param str autocomplete: Partial search query + :param str name: Document name + :param str subdomain: + :param str signer_emails: Email needed to sign/approve + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending + :param str who: `m`: only me, `mo`: me and others, `o`: only others + :param str format: Export format, can be `json` (default), `csv`, or `xls` + :param float signer_data: Set to `1` to export with each signer on a separate row :return: InlineResponse2002 If the method is called asynchronously, returns the request thread. @@ -68,12 +77,21 @@ def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 :param async bool :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. + :param str q: Normal search query + :param str autocomplete: Partial search query + :param str name: Document name + :param str subdomain: + :param str signer_emails: Email needed to sign/approve + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending + :param str who: `m`: only me, `mo`: me and others, `o`: only others + :param str format: Export format, can be `json` (default), `csv`, or `xls` + :param float signer_data: Set to `1` to export with each signer on a separate row :return: InlineResponse2002 If the method is called asynchronously, returns the request thread. """ - all_params = ['page', 'limit'] # noqa: E501 + all_params = ['page', 'limit', 'q', 'autocomplete', 'name', 'subdomain', 'signer_emails', 'status', 'who', 'format', 'signer_data'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -98,6 +116,24 @@ def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 query_params.append(('page', params['page'])) # noqa: E501 if 'limit' in params: query_params.append(('limit', params['limit'])) # noqa: E501 + if 'q' in params: + query_params.append(('q', params['q'])) # noqa: E501 + if 'autocomplete' in params: + query_params.append(('autocomplete', params['autocomplete'])) # noqa: E501 + if 'name' in params: + query_params.append(('name', params['name'])) # noqa: E501 + if 'subdomain' in params: + query_params.append(('subdomain', params['subdomain'])) # noqa: E501 + if 'signer_emails' in params: + query_params.append(('signer_emails', params['signer_emails'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'who' in params: + query_params.append(('who', params['who'])) # noqa: E501 + if 'format' in params: + query_params.append(('format', params['format'])) # noqa: E501 + if 'signer_data' in params: + query_params.append(('signer_data', params['signer_data'])) # noqa: E501 header_params = {} From 9200a434a1931bb312554a5f20034eba9aeb0ac2 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Wed, 17 Oct 2018 18:13:02 +0200 Subject: [PATCH 04/18] Make parent_doc read only --- .../models/document_search.py | 63 +++++++++---------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py index 3edec13..672cd29 100644 --- a/signrequest_python_client/models/document_search.py +++ b/signrequest_python_client/models/document_search.py @@ -36,7 +36,6 @@ class DocumentSearch(object): 'who': 'str', 'nr_extra_docs': 'int', 'from_email': 'str', - 'parent_doc': 'str', 'uuid': 'str', 'created': 'datetime', 'autocomplete': 'str', @@ -45,7 +44,8 @@ class DocumentSearch(object): 'signer_emails': 'list[str]', 'status_display': 'str', 'created_timestamp': 'int', - 'finished_on_timestamp': 'int' + 'finished_on_timestamp': 'int', + 'parent_doc': 'str' } attribute_map = { @@ -54,7 +54,6 @@ class DocumentSearch(object): 'who': 'who', 'nr_extra_docs': 'nr_extra_docs', 'from_email': 'from_email', - 'parent_doc': 'parent_doc', 'uuid': 'uuid', 'created': 'created', 'autocomplete': 'autocomplete', @@ -63,10 +62,11 @@ class DocumentSearch(object): 'signer_emails': 'signer_emails', 'status_display': 'status_display', 'created_timestamp': 'created_timestamp', - 'finished_on_timestamp': 'finished_on_timestamp' + 'finished_on_timestamp': 'finished_on_timestamp', + 'parent_doc': 'parent_doc' } - def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, parent_doc=None, uuid=None, created=None, autocomplete=None, finished_on=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None): # noqa: E501 + def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, finished_on=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None): # noqa: E501 """DocumentSearch - a model defined in Swagger""" # noqa: E501 self._status = None @@ -74,7 +74,6 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self._who = None self._nr_extra_docs = None self._from_email = None - self._parent_doc = None self._uuid = None self._created = None self._autocomplete = None @@ -84,6 +83,7 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self._status_display = None self._created_timestamp = None self._finished_on_timestamp = None + self._parent_doc = None self.discriminator = None if status is not None: @@ -93,7 +93,6 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self.who = who self.nr_extra_docs = nr_extra_docs self.from_email = from_email - self.parent_doc = parent_doc if uuid is not None: self.uuid = uuid if created is not None: @@ -109,6 +108,8 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self.created_timestamp = created_timestamp if finished_on_timestamp is not None: self.finished_on_timestamp = finished_on_timestamp + if parent_doc is not None: + self.parent_doc = parent_doc @property def status(self): @@ -235,31 +236,6 @@ def from_email(self, from_email): self._from_email = from_email - @property - def parent_doc(self): - """Gets the parent_doc of this DocumentSearch. # noqa: E501 - - - :return: The parent_doc of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._parent_doc - - @parent_doc.setter - def parent_doc(self, parent_doc): - """Sets the parent_doc of this DocumentSearch. - - - :param parent_doc: The parent_doc of this DocumentSearch. # noqa: E501 - :type: str - """ - if parent_doc is None: - raise ValueError("Invalid value for `parent_doc`, must not be `None`") # noqa: E501 - if parent_doc is not None and len(parent_doc) < 1: - raise ValueError("Invalid value for `parent_doc`, length must be greater than or equal to `1`") # noqa: E501 - - self._parent_doc = parent_doc - @property def uuid(self): """Gets the uuid of this DocumentSearch. # noqa: E501 @@ -463,6 +439,29 @@ def finished_on_timestamp(self, finished_on_timestamp): self._finished_on_timestamp = finished_on_timestamp + @property + def parent_doc(self): + """Gets the parent_doc of this DocumentSearch. # noqa: E501 + + + :return: The parent_doc of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._parent_doc + + @parent_doc.setter + def parent_doc(self, parent_doc): + """Sets the parent_doc of this DocumentSearch. + + + :param parent_doc: The parent_doc of this DocumentSearch. # noqa: E501 + :type: str + """ + if parent_doc is not None and len(parent_doc) < 1: + raise ValueError("Invalid value for `parent_doc`, length must be greater than or equal to `1`") # noqa: E501 + + self._parent_doc = parent_doc + def to_dict(self): """Returns the model properties as a dict""" result = {} From c39f28d874005c40475600b8d38dfca5474a7a0a Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Wed, 17 Oct 2018 18:18:09 +0200 Subject: [PATCH 05/18] Make finished_on read only --- .../models/document_search.py | 59 +++++++++---------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py index 672cd29..e9594f1 100644 --- a/signrequest_python_client/models/document_search.py +++ b/signrequest_python_client/models/document_search.py @@ -39,13 +39,13 @@ class DocumentSearch(object): 'uuid': 'str', 'created': 'datetime', 'autocomplete': 'str', - 'finished_on': 'datetime', 'subdomain': 'str', 'signer_emails': 'list[str]', 'status_display': 'str', 'created_timestamp': 'int', 'finished_on_timestamp': 'int', - 'parent_doc': 'str' + 'parent_doc': 'str', + 'finished_on': 'datetime' } attribute_map = { @@ -57,16 +57,16 @@ class DocumentSearch(object): 'uuid': 'uuid', 'created': 'created', 'autocomplete': 'autocomplete', - 'finished_on': 'finished_on', 'subdomain': 'subdomain', 'signer_emails': 'signer_emails', 'status_display': 'status_display', 'created_timestamp': 'created_timestamp', 'finished_on_timestamp': 'finished_on_timestamp', - 'parent_doc': 'parent_doc' + 'parent_doc': 'parent_doc', + 'finished_on': 'finished_on' } - def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, finished_on=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None): # noqa: E501 + def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None, finished_on=None): # noqa: E501 """DocumentSearch - a model defined in Swagger""" # noqa: E501 self._status = None @@ -77,13 +77,13 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self._uuid = None self._created = None self._autocomplete = None - self._finished_on = None self._subdomain = None self._signer_emails = None self._status_display = None self._created_timestamp = None self._finished_on_timestamp = None self._parent_doc = None + self._finished_on = None self.discriminator = None if status is not None: @@ -98,7 +98,6 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em if created is not None: self.created = created self.autocomplete = autocomplete - self.finished_on = finished_on self.subdomain = subdomain if signer_emails is not None: self.signer_emails = signer_emails @@ -110,6 +109,8 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self.finished_on_timestamp = finished_on_timestamp if parent_doc is not None: self.parent_doc = parent_doc + if finished_on is not None: + self.finished_on = finished_on @property def status(self): @@ -305,29 +306,6 @@ def autocomplete(self, autocomplete): self._autocomplete = autocomplete - @property - def finished_on(self): - """Gets the finished_on of this DocumentSearch. # noqa: E501 - - - :return: The finished_on of this DocumentSearch. # noqa: E501 - :rtype: datetime - """ - return self._finished_on - - @finished_on.setter - def finished_on(self, finished_on): - """Sets the finished_on of this DocumentSearch. - - - :param finished_on: The finished_on of this DocumentSearch. # noqa: E501 - :type: datetime - """ - if finished_on is None: - raise ValueError("Invalid value for `finished_on`, must not be `None`") # noqa: E501 - - self._finished_on = finished_on - @property def subdomain(self): """Gets the subdomain of this DocumentSearch. # noqa: E501 @@ -462,6 +440,27 @@ def parent_doc(self, parent_doc): self._parent_doc = parent_doc + @property + def finished_on(self): + """Gets the finished_on of this DocumentSearch. # noqa: E501 + + + :return: The finished_on of this DocumentSearch. # noqa: E501 + :rtype: datetime + """ + return self._finished_on + + @finished_on.setter + def finished_on(self, finished_on): + """Sets the finished_on of this DocumentSearch. + + + :param finished_on: The finished_on of this DocumentSearch. # noqa: E501 + :type: datetime + """ + + self._finished_on = finished_on + def to_dict(self): """Returns the model properties as a dict""" result = {} From 5c68ce6157a4765bfe642d815c8b3d7c1908f092 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Wed, 17 Oct 2018 18:38:47 +0200 Subject: [PATCH 06/18] Make subdomain read only --- docs/DocumentSearch.md | 6 +- .../models/document_search.py | 63 +++++++++---------- 2 files changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/DocumentSearch.md b/docs/DocumentSearch.md index 5e868e1..4ab4448 100644 --- a/docs/DocumentSearch.md +++ b/docs/DocumentSearch.md @@ -8,16 +8,16 @@ Name | Type | Description | Notes **who** | **str** | | **nr_extra_docs** | **int** | | **from_email** | **str** | | -**parent_doc** | **str** | | **uuid** | **str** | | [optional] **created** | **datetime** | | [optional] **autocomplete** | **str** | | -**finished_on** | **datetime** | | -**subdomain** | **str** | | **signer_emails** | **list[str]** | | [optional] **status_display** | **str** | | [optional] **created_timestamp** | **int** | | [optional] **finished_on_timestamp** | **int** | | [optional] +**parent_doc** | **str** | | [optional] +**finished_on** | **datetime** | | [optional] +**subdomain** | **str** | | [optional] [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py index e9594f1..82c8a1e 100644 --- a/signrequest_python_client/models/document_search.py +++ b/signrequest_python_client/models/document_search.py @@ -39,13 +39,13 @@ class DocumentSearch(object): 'uuid': 'str', 'created': 'datetime', 'autocomplete': 'str', - 'subdomain': 'str', 'signer_emails': 'list[str]', 'status_display': 'str', 'created_timestamp': 'int', 'finished_on_timestamp': 'int', 'parent_doc': 'str', - 'finished_on': 'datetime' + 'finished_on': 'datetime', + 'subdomain': 'str' } attribute_map = { @@ -57,16 +57,16 @@ class DocumentSearch(object): 'uuid': 'uuid', 'created': 'created', 'autocomplete': 'autocomplete', - 'subdomain': 'subdomain', 'signer_emails': 'signer_emails', 'status_display': 'status_display', 'created_timestamp': 'created_timestamp', 'finished_on_timestamp': 'finished_on_timestamp', 'parent_doc': 'parent_doc', - 'finished_on': 'finished_on' + 'finished_on': 'finished_on', + 'subdomain': 'subdomain' } - def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, subdomain=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None, finished_on=None): # noqa: E501 + def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None, finished_on=None, subdomain=None): # noqa: E501 """DocumentSearch - a model defined in Swagger""" # noqa: E501 self._status = None @@ -77,13 +77,13 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self._uuid = None self._created = None self._autocomplete = None - self._subdomain = None self._signer_emails = None self._status_display = None self._created_timestamp = None self._finished_on_timestamp = None self._parent_doc = None self._finished_on = None + self._subdomain = None self.discriminator = None if status is not None: @@ -98,7 +98,6 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em if created is not None: self.created = created self.autocomplete = autocomplete - self.subdomain = subdomain if signer_emails is not None: self.signer_emails = signer_emails if status_display is not None: @@ -111,6 +110,8 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em self.parent_doc = parent_doc if finished_on is not None: self.finished_on = finished_on + if subdomain is not None: + self.subdomain = subdomain @property def status(self): @@ -306,31 +307,6 @@ def autocomplete(self, autocomplete): self._autocomplete = autocomplete - @property - def subdomain(self): - """Gets the subdomain of this DocumentSearch. # noqa: E501 - - - :return: The subdomain of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._subdomain - - @subdomain.setter - def subdomain(self, subdomain): - """Sets the subdomain of this DocumentSearch. - - - :param subdomain: The subdomain of this DocumentSearch. # noqa: E501 - :type: str - """ - if subdomain is None: - raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 - if subdomain is not None and len(subdomain) < 1: - raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 - - self._subdomain = subdomain - @property def signer_emails(self): """Gets the signer_emails of this DocumentSearch. # noqa: E501 @@ -461,6 +437,29 @@ def finished_on(self, finished_on): self._finished_on = finished_on + @property + def subdomain(self): + """Gets the subdomain of this DocumentSearch. # noqa: E501 + + + :return: The subdomain of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this DocumentSearch. + + + :param subdomain: The subdomain of this DocumentSearch. # noqa: E501 + :type: str + """ + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + + self._subdomain = subdomain + def to_dict(self): """Returns the model properties as a dict""" result = {} From 7d6e371e878d2ec4e25bf8179a7e5c47763d80b7 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Thu, 18 Oct 2018 12:01:33 +0200 Subject: [PATCH 07/18] Remove body parameter from signrequests_cancel_signrequest and signrequests_resend_signrequest_email --- docs/SignrequestsApi.md | 12 ++--- .../api/signrequests_api.py | 44 ++++++------------- 2 files changed, 18 insertions(+), 38 deletions(-) diff --git a/docs/SignrequestsApi.md b/docs/SignrequestsApi.md index c04ebf8..03b3dec 100644 --- a/docs/SignrequestsApi.md +++ b/docs/SignrequestsApi.md @@ -12,7 +12,7 @@ Method | HTTP request | Description # **signrequests_cancel_signrequest** -> SignRequest signrequests_cancel_signrequest(uuid, data) +> SignRequest signrequests_cancel_signrequest(uuid) Cancel a SignRequest @@ -34,11 +34,10 @@ configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) uuid = 'uuid_example' # str | -data = signrequest_python_client.SignRequest() # SignRequest | try: # Cancel a SignRequest - api_response = api_instance.signrequests_cancel_signrequest(uuid, data) + api_response = api_instance.signrequests_cancel_signrequest(uuid) pprint(api_response) except ApiException as e: print("Exception when calling SignrequestsApi->signrequests_cancel_signrequest: %s\n" % e) @@ -49,7 +48,6 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **uuid** | **str**| | - **data** | [**SignRequest**](SignRequest.md)| | ### Return type @@ -228,7 +226,7 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **signrequests_resend_signrequest_email** -> SignRequest signrequests_resend_signrequest_email(uuid, data) +> SignRequest signrequests_resend_signrequest_email(uuid) Resend a SignRequest @@ -250,11 +248,10 @@ configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) uuid = 'uuid_example' # str | -data = signrequest_python_client.SignRequest() # SignRequest | try: # Resend a SignRequest - api_response = api_instance.signrequests_resend_signrequest_email(uuid, data) + api_response = api_instance.signrequests_resend_signrequest_email(uuid) pprint(api_response) except ApiException as e: print("Exception when calling SignrequestsApi->signrequests_resend_signrequest_email: %s\n" % e) @@ -265,7 +262,6 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **uuid** | **str**| | - **data** | [**SignRequest**](SignRequest.md)| | ### Return type diff --git a/signrequest_python_client/api/signrequests_api.py b/signrequest_python_client/api/signrequests_api.py index 7ed4d0e..6e14f2a 100644 --- a/signrequest_python_client/api/signrequests_api.py +++ b/signrequest_python_client/api/signrequests_api.py @@ -33,47 +33,45 @@ def __init__(self, api_client=None): api_client = ApiClient() self.api_client = api_client - def signrequests_cancel_signrequest(self, uuid, data, **kwargs): # noqa: E501 + def signrequests_cancel_signrequest(self, uuid, **kwargs): # noqa: E501 """Cancel a SignRequest # noqa: E501 # noqa: E501 This method makes a synchronous HTTP request by default. To make an asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_cancel_signrequest(uuid, data, async=True) + >>> thread = api.signrequests_cancel_signrequest(uuid, async=True) >>> result = thread.get() :param async bool :param str uuid: (required) - :param SignRequest data: (required) :return: SignRequest If the method is called asynchronously, returns the request thread. """ kwargs['_return_http_data_only'] = True if kwargs.get('async'): - return self.signrequests_cancel_signrequest_with_http_info(uuid, data, **kwargs) # noqa: E501 + return self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 else: - (data) = self.signrequests_cancel_signrequest_with_http_info(uuid, data, **kwargs) # noqa: E501 + (data) = self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 return data - def signrequests_cancel_signrequest_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + def signrequests_cancel_signrequest_with_http_info(self, uuid, **kwargs): # noqa: E501 """Cancel a SignRequest # noqa: E501 # noqa: E501 This method makes a synchronous HTTP request by default. To make an asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_cancel_signrequest_with_http_info(uuid, data, async=True) + >>> thread = api.signrequests_cancel_signrequest_with_http_info(uuid, async=True) >>> result = thread.get() :param async bool :param str uuid: (required) - :param SignRequest data: (required) :return: SignRequest If the method is called asynchronously, returns the request thread. """ - all_params = ['uuid', 'data'] # noqa: E501 + all_params = ['uuid'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -92,10 +90,6 @@ def signrequests_cancel_signrequest_with_http_info(self, uuid, data, **kwargs): if ('uuid' not in params or params['uuid'] is None): raise ValueError("Missing the required parameter `uuid` when calling `signrequests_cancel_signrequest`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `signrequests_cancel_signrequest`") # noqa: E501 collection_formats = {} @@ -111,8 +105,6 @@ def signrequests_cancel_signrequest_with_http_info(self, uuid, data, **kwargs): local_var_files = {} body_params = None - if 'data' in params: - body_params = params['data'] # HTTP header `Accept` header_params['Accept'] = self.api_client.select_header_accept( ['application/json']) # noqa: E501 @@ -437,47 +429,45 @@ def signrequests_read_with_http_info(self, uuid, **kwargs): # noqa: E501 _request_timeout=params.get('_request_timeout'), collection_formats=collection_formats) - def signrequests_resend_signrequest_email(self, uuid, data, **kwargs): # noqa: E501 + def signrequests_resend_signrequest_email(self, uuid, **kwargs): # noqa: E501 """Resend a SignRequest # noqa: E501 # noqa: E501 This method makes a synchronous HTTP request by default. To make an asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_resend_signrequest_email(uuid, data, async=True) + >>> thread = api.signrequests_resend_signrequest_email(uuid, async=True) >>> result = thread.get() :param async bool :param str uuid: (required) - :param SignRequest data: (required) :return: SignRequest If the method is called asynchronously, returns the request thread. """ kwargs['_return_http_data_only'] = True if kwargs.get('async'): - return self.signrequests_resend_signrequest_email_with_http_info(uuid, data, **kwargs) # noqa: E501 + return self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 else: - (data) = self.signrequests_resend_signrequest_email_with_http_info(uuid, data, **kwargs) # noqa: E501 + (data) = self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 return data - def signrequests_resend_signrequest_email_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + def signrequests_resend_signrequest_email_with_http_info(self, uuid, **kwargs): # noqa: E501 """Resend a SignRequest # noqa: E501 # noqa: E501 This method makes a synchronous HTTP request by default. To make an asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_resend_signrequest_email_with_http_info(uuid, data, async=True) + >>> thread = api.signrequests_resend_signrequest_email_with_http_info(uuid, async=True) >>> result = thread.get() :param async bool :param str uuid: (required) - :param SignRequest data: (required) :return: SignRequest If the method is called asynchronously, returns the request thread. """ - all_params = ['uuid', 'data'] # noqa: E501 + all_params = ['uuid'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -496,10 +486,6 @@ def signrequests_resend_signrequest_email_with_http_info(self, uuid, data, **kwa if ('uuid' not in params or params['uuid'] is None): raise ValueError("Missing the required parameter `uuid` when calling `signrequests_resend_signrequest_email`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `signrequests_resend_signrequest_email`") # noqa: E501 collection_formats = {} @@ -515,8 +501,6 @@ def signrequests_resend_signrequest_email_with_http_info(self, uuid, data, **kwa local_var_files = {} body_params = None - if 'data' in params: - body_params = params['data'] # HTTP header `Accept` header_params['Accept'] = self.api_client.select_header_accept( ['application/json']) # noqa: E501 From ce63763cce86f38e7c90bbc88be001ccb6678978 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Thu, 18 Oct 2018 12:13:00 +0200 Subject: [PATCH 08/18] Make signers not required on SignRequest model --- docs/SignRequest.md | 2 +- docs/SignRequestQuickCreate.md | 2 +- signrequest_python_client/models/sign_request.py | 5 ++--- .../models/sign_request_quick_create.py | 5 ++--- 4 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/SignRequest.md b/docs/SignRequest.md index 6cd76d4..80b2cbf 100644 --- a/docs/SignRequest.md +++ b/docs/SignRequest.md @@ -19,7 +19,7 @@ Name | Type | Description | Notes **message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] **who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] **send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] -**signers** | [**list[Signer]**](Signer.md) | | +**signers** | [**list[Signer]**](Signer.md) | | [optional] **uuid** | **str** | | [optional] **url** | **str** | | [optional] **document** | **str** | | diff --git a/docs/SignRequestQuickCreate.md b/docs/SignRequestQuickCreate.md index 57f1ac3..5bcf5cd 100644 --- a/docs/SignRequestQuickCreate.md +++ b/docs/SignRequestQuickCreate.md @@ -19,7 +19,7 @@ Name | Type | Description | Notes **message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] **who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] **send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] -**signers** | [**list[Signer]**](Signer.md) | | +**signers** | [**list[Signer]**](Signer.md) | | [optional] **uuid** | **str** | | [optional] **url** | **str** | | [optional] **document** | **str** | | [optional] diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py index f069864..98a0aab 100644 --- a/signrequest_python_client/models/sign_request.py +++ b/signrequest_python_client/models/sign_request.py @@ -142,7 +142,8 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.who = who if send_reminders is not None: self.send_reminders = send_reminders - self.signers = signers + if signers is not None: + self.signers = signers if uuid is not None: self.uuid = uuid if url is not None: @@ -555,8 +556,6 @@ def signers(self, signers): :param signers: The signers of this SignRequest. # noqa: E501 :type: list[Signer] """ - if signers is None: - raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 self._signers = signers diff --git a/signrequest_python_client/models/sign_request_quick_create.py b/signrequest_python_client/models/sign_request_quick_create.py index 59d98c7..f3506d2 100644 --- a/signrequest_python_client/models/sign_request_quick_create.py +++ b/signrequest_python_client/models/sign_request_quick_create.py @@ -184,7 +184,8 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.who = who if send_reminders is not None: self.send_reminders = send_reminders - self.signers = signers + if signers is not None: + self.signers = signers if uuid is not None: self.uuid = uuid if url is not None: @@ -624,8 +625,6 @@ def signers(self, signers): :param signers: The signers of this SignRequestQuickCreate. # noqa: E501 :type: list[Signer] """ - if signers is None: - raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 self._signers = signers From a38f3b197db281cb7de4dcbdc4ab6c15f8538101 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Thu, 18 Oct 2018 12:15:40 +0200 Subject: [PATCH 09/18] Make document optional on SignRequest model --- docs/SignRequest.md | 2 +- signrequest_python_client/models/sign_request.py | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/SignRequest.md b/docs/SignRequest.md index 80b2cbf..a4e2fcc 100644 --- a/docs/SignRequest.md +++ b/docs/SignRequest.md @@ -22,7 +22,7 @@ Name | Type | Description | Notes **signers** | [**list[Signer]**](Signer.md) | | [optional] **uuid** | **str** | | [optional] **url** | **str** | | [optional] -**document** | **str** | | +**document** | **str** | | [optional] **integration** | **str** | | [optional] **integration_data** | **str** | | [optional] diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py index 98a0aab..1be9c0f 100644 --- a/signrequest_python_client/models/sign_request.py +++ b/signrequest_python_client/models/sign_request.py @@ -148,7 +148,8 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.uuid = uuid if url is not None: self.url = url - self.document = document + if document is not None: + self.document = document if integration is not None: self.integration = integration if integration_data is not None: @@ -621,8 +622,6 @@ def document(self, document): :param document: The document of this SignRequest. # noqa: E501 :type: str """ - if document is None: - raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 self._document = document From 1101f3664d6bbd26ab211376d70082e03fe888bb Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Fri, 19 Oct 2018 13:56:52 +0200 Subject: [PATCH 10/18] Add missing document attachment list parameters, make document optional --- docs/DocumentAttachment.md | 2 +- docs/DocumentAttachmentsApi.md | 10 ++++++++-- .../api/document_attachments_api.py | 14 +++++++++++++- .../models/document_attachment.py | 5 ++--- 4 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/DocumentAttachment.md b/docs/DocumentAttachment.md index f7d1f15..e593c84 100644 --- a/docs/DocumentAttachment.md +++ b/docs/DocumentAttachment.md @@ -10,7 +10,7 @@ Name | Type | Description | Notes **file_from_content** | **str** | Base64 encoded document content | [optional] **file_from_content_name** | **str** | Filename, including extension. Required when using `file_from_content`. | [optional] **file_from_url** | **str** | Publicly accessible URL of document to be downloaded by SignRequest | [optional] -**document** | **str** | | +**document** | **str** | | [optional] [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/docs/DocumentAttachmentsApi.md b/docs/DocumentAttachmentsApi.md index b578c85..7815f7a 100644 --- a/docs/DocumentAttachmentsApi.md +++ b/docs/DocumentAttachmentsApi.md @@ -63,7 +63,7 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **document_attachments_list** -> InlineResponse2001 document_attachments_list(page=page, limit=limit) +> InlineResponse2001 document_attachments_list(document__uuid=document__uuid, document__external_id=document__external_id, created=created, page=page, limit=limit) Retrieve a list of Document Attachments @@ -85,12 +85,15 @@ configuration.api_key['Authorization'] = 'YOUR_API_KEY' # create an instance of the API class api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +document__uuid = 'document__uuid_example' # str | (optional) +document__external_id = 'document__external_id_example' # str | (optional) +created = 'created_example' # str | (optional) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) try: # Retrieve a list of Document Attachments - api_response = api_instance.document_attachments_list(page=page, limit=limit) + api_response = api_instance.document_attachments_list(document__uuid=document__uuid, document__external_id=document__external_id, created=created, page=page, limit=limit) pprint(api_response) except ApiException as e: print("Exception when calling DocumentAttachmentsApi->document_attachments_list: %s\n" % e) @@ -100,6 +103,9 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- + **document__uuid** | **str**| | [optional] + **document__external_id** | **str**| | [optional] + **created** | **str**| | [optional] **page** | **int**| A page number within the paginated result set. | [optional] **limit** | **int**| Number of results to return per page. | [optional] diff --git a/signrequest_python_client/api/document_attachments_api.py b/signrequest_python_client/api/document_attachments_api.py index 51f987d..3e05d80 100644 --- a/signrequest_python_client/api/document_attachments_api.py +++ b/signrequest_python_client/api/document_attachments_api.py @@ -142,6 +142,9 @@ def document_attachments_list(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str document__uuid: + :param str document__external_id: + :param str created: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2001 @@ -165,6 +168,9 @@ def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str document__uuid: + :param str document__external_id: + :param str created: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2001 @@ -172,7 +178,7 @@ def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 returns the request thread. """ - all_params = ['page', 'limit'] # noqa: E501 + all_params = ['document__uuid', 'document__external_id', 'created', 'page', 'limit'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -193,6 +199,12 @@ def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 path_params = {} query_params = [] + if 'document__uuid' in params: + query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 + if 'document__external_id' in params: + query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 + if 'created' in params: + query_params.append(('created', params['created'])) # noqa: E501 if 'page' in params: query_params.append(('page', params['page'])) # noqa: E501 if 'limit' in params: diff --git a/signrequest_python_client/models/document_attachment.py b/signrequest_python_client/models/document_attachment.py index 198b560..2129f0a 100644 --- a/signrequest_python_client/models/document_attachment.py +++ b/signrequest_python_client/models/document_attachment.py @@ -79,7 +79,8 @@ def __init__(self, url=None, uuid=None, name=None, file=None, file_from_content= self.file_from_content_name = file_from_content_name if file_from_url is not None: self.file_from_url = file_from_url - self.document = document + if document is not None: + self.document = document @property def url(self): @@ -262,8 +263,6 @@ def document(self, document): :param document: The document of this DocumentAttachment. # noqa: E501 :type: str """ - if document is None: - raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 self._document = document From 9e7cc5d67ad102c298c4786bb7953271628b747d Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Fri, 19 Oct 2018 13:58:51 +0200 Subject: [PATCH 11/18] Add missing "who" and "from_email" parameters to signrequest_api --- docs/SignrequestsApi.md | 8 ++++++-- signrequest_python_client/api/signrequests_api.py | 10 +++++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/SignrequestsApi.md b/docs/SignrequestsApi.md index 03b3dec..34d886a 100644 --- a/docs/SignrequestsApi.md +++ b/docs/SignrequestsApi.md @@ -118,7 +118,7 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **signrequests_list** -> InlineResponse2005 signrequests_list(page=page, limit=limit) +> InlineResponse2005 signrequests_list(who=who, from_email=from_email, page=page, limit=limit) Retrieve a list of SignRequests @@ -139,12 +139,14 @@ configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +who = 'who_example' # str | (optional) +from_email = 'from_email_example' # str | (optional) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) try: # Retrieve a list of SignRequests - api_response = api_instance.signrequests_list(page=page, limit=limit) + api_response = api_instance.signrequests_list(who=who, from_email=from_email, page=page, limit=limit) pprint(api_response) except ApiException as e: print("Exception when calling SignrequestsApi->signrequests_list: %s\n" % e) @@ -154,6 +156,8 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- + **who** | **str**| | [optional] + **from_email** | **str**| | [optional] **page** | **int**| A page number within the paginated result set. | [optional] **limit** | **int**| Number of results to return per page. | [optional] diff --git a/signrequest_python_client/api/signrequests_api.py b/signrequest_python_client/api/signrequests_api.py index 6e14f2a..0938259 100644 --- a/signrequest_python_client/api/signrequests_api.py +++ b/signrequest_python_client/api/signrequests_api.py @@ -241,6 +241,8 @@ def signrequests_list(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str who: + :param str from_email: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2005 @@ -264,6 +266,8 @@ def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str who: + :param str from_email: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2005 @@ -271,7 +275,7 @@ def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 returns the request thread. """ - all_params = ['page', 'limit'] # noqa: E501 + all_params = ['who', 'from_email', 'page', 'limit'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -292,6 +296,10 @@ def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 path_params = {} query_params = [] + if 'who' in params: + query_params.append(('who', params['who'])) # noqa: E501 + if 'from_email' in params: + query_params.append(('from_email', params['from_email'])) # noqa: E501 if 'page' in params: query_params.append(('page', params['page'])) # noqa: E501 if 'limit' in params: From 46d1e0e212026c5817e36b9f0f1017d8e28b8062 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Fri, 19 Oct 2018 14:03:15 +0200 Subject: [PATCH 12/18] Add missing parameters to documents_list --- docs/DocumentsApi.md | 22 ++++++++++- .../api/documents_api.py | 38 ++++++++++++++++++- 2 files changed, 57 insertions(+), 3 deletions(-) diff --git a/docs/DocumentsApi.md b/docs/DocumentsApi.md index 3889217..c48bee9 100644 --- a/docs/DocumentsApi.md +++ b/docs/DocumentsApi.md @@ -116,7 +116,7 @@ void (empty response body) [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **documents_list** -> InlineResponse2003 documents_list(page=page, limit=limit) +> InlineResponse2003 documents_list(external_id=external_id, signrequest__who=signrequest__who, signrequest__from_email=signrequest__from_email, status=status, user__email=user__email, user__first_name=user__first_name, user__last_name=user__last_name, created=created, modified=modified, page=page, limit=limit) Retrieve a list of Documents @@ -137,12 +137,21 @@ configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +external_id = 'external_id_example' # str | (optional) +signrequest__who = 'signrequest__who_example' # str | (optional) +signrequest__from_email = 'signrequest__from_email_example' # str | (optional) +status = 'status_example' # str | (optional) +user__email = 'user__email_example' # str | (optional) +user__first_name = 'user__first_name_example' # str | (optional) +user__last_name = 'user__last_name_example' # str | (optional) +created = 'created_example' # str | (optional) +modified = 'modified_example' # str | (optional) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) try: # Retrieve a list of Documents - api_response = api_instance.documents_list(page=page, limit=limit) + api_response = api_instance.documents_list(external_id=external_id, signrequest__who=signrequest__who, signrequest__from_email=signrequest__from_email, status=status, user__email=user__email, user__first_name=user__first_name, user__last_name=user__last_name, created=created, modified=modified, page=page, limit=limit) pprint(api_response) except ApiException as e: print("Exception when calling DocumentsApi->documents_list: %s\n" % e) @@ -152,6 +161,15 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- + **external_id** | **str**| | [optional] + **signrequest__who** | **str**| | [optional] + **signrequest__from_email** | **str**| | [optional] + **status** | **str**| | [optional] + **user__email** | **str**| | [optional] + **user__first_name** | **str**| | [optional] + **user__last_name** | **str**| | [optional] + **created** | **str**| | [optional] + **modified** | **str**| | [optional] **page** | **int**| A page number within the paginated result set. | [optional] **limit** | **int**| Number of results to return per page. | [optional] diff --git a/signrequest_python_client/api/documents_api.py b/signrequest_python_client/api/documents_api.py index 95508f3..7859e27 100644 --- a/signrequest_python_client/api/documents_api.py +++ b/signrequest_python_client/api/documents_api.py @@ -241,6 +241,15 @@ def documents_list(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str external_id: + :param str signrequest__who: + :param str signrequest__from_email: + :param str status: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param str created: + :param str modified: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2003 @@ -264,6 +273,15 @@ def documents_list_with_http_info(self, **kwargs): # noqa: E501 >>> result = thread.get() :param async bool + :param str external_id: + :param str signrequest__who: + :param str signrequest__from_email: + :param str status: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param str created: + :param str modified: :param int page: A page number within the paginated result set. :param int limit: Number of results to return per page. :return: InlineResponse2003 @@ -271,7 +289,7 @@ def documents_list_with_http_info(self, **kwargs): # noqa: E501 returns the request thread. """ - all_params = ['page', 'limit'] # noqa: E501 + all_params = ['external_id', 'signrequest__who', 'signrequest__from_email', 'status', 'user__email', 'user__first_name', 'user__last_name', 'created', 'modified', 'page', 'limit'] # noqa: E501 all_params.append('async') all_params.append('_return_http_data_only') all_params.append('_preload_content') @@ -292,6 +310,24 @@ def documents_list_with_http_info(self, **kwargs): # noqa: E501 path_params = {} query_params = [] + if 'external_id' in params: + query_params.append(('external_id', params['external_id'])) # noqa: E501 + if 'signrequest__who' in params: + query_params.append(('signrequest__who', params['signrequest__who'])) # noqa: E501 + if 'signrequest__from_email' in params: + query_params.append(('signrequest__from_email', params['signrequest__from_email'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'user__email' in params: + query_params.append(('user__email', params['user__email'])) # noqa: E501 + if 'user__first_name' in params: + query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 + if 'user__last_name' in params: + query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 + if 'created' in params: + query_params.append(('created', params['created'])) # noqa: E501 + if 'modified' in params: + query_params.append(('modified', params['modified'])) # noqa: E501 if 'page' in params: query_params.append(('page', params['page'])) # noqa: E501 if 'limit' in params: From 615299e6465ac7ba84408121147829c5ff0a19f4 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Mon, 22 Oct 2018 13:37:16 +0200 Subject: [PATCH 13/18] Revert "Make signers not required on SignRequest model" This reverts commit 12aae7c391f3970c81cd2ca0ba7551a4abc80530. --- docs/SignRequest.md | 2 +- docs/SignRequestQuickCreate.md | 2 +- signrequest_python_client/models/sign_request.py | 5 +++-- .../models/sign_request_quick_create.py | 5 +++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/SignRequest.md b/docs/SignRequest.md index a4e2fcc..c09a48f 100644 --- a/docs/SignRequest.md +++ b/docs/SignRequest.md @@ -19,7 +19,7 @@ Name | Type | Description | Notes **message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] **who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] **send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] -**signers** | [**list[Signer]**](Signer.md) | | [optional] +**signers** | [**list[Signer]**](Signer.md) | | **uuid** | **str** | | [optional] **url** | **str** | | [optional] **document** | **str** | | [optional] diff --git a/docs/SignRequestQuickCreate.md b/docs/SignRequestQuickCreate.md index 5bcf5cd..57f1ac3 100644 --- a/docs/SignRequestQuickCreate.md +++ b/docs/SignRequestQuickCreate.md @@ -19,7 +19,7 @@ Name | Type | Description | Notes **message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] **who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] [default to 'o'] **send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] -**signers** | [**list[Signer]**](Signer.md) | | [optional] +**signers** | [**list[Signer]**](Signer.md) | | **uuid** | **str** | | [optional] **url** | **str** | | [optional] **document** | **str** | | [optional] diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py index 1be9c0f..afa2c77 100644 --- a/signrequest_python_client/models/sign_request.py +++ b/signrequest_python_client/models/sign_request.py @@ -142,8 +142,7 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.who = who if send_reminders is not None: self.send_reminders = send_reminders - if signers is not None: - self.signers = signers + self.signers = signers if uuid is not None: self.uuid = uuid if url is not None: @@ -557,6 +556,8 @@ def signers(self, signers): :param signers: The signers of this SignRequest. # noqa: E501 :type: list[Signer] """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 self._signers = signers diff --git a/signrequest_python_client/models/sign_request_quick_create.py b/signrequest_python_client/models/sign_request_quick_create.py index f3506d2..59d98c7 100644 --- a/signrequest_python_client/models/sign_request_quick_create.py +++ b/signrequest_python_client/models/sign_request_quick_create.py @@ -184,8 +184,7 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.who = who if send_reminders is not None: self.send_reminders = send_reminders - if signers is not None: - self.signers = signers + self.signers = signers if uuid is not None: self.uuid = uuid if url is not None: @@ -625,6 +624,8 @@ def signers(self, signers): :param signers: The signers of this SignRequestQuickCreate. # noqa: E501 :type: list[Signer] """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 self._signers = signers From e354e175b94b4e54469f9e48d3122478d3743f92 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Mon, 22 Oct 2018 13:37:24 +0200 Subject: [PATCH 14/18] Revert "Make document optional on SignRequest model" This reverts commit 4553fbede2be29b9a5ae4b2226c494d7a68485ac. --- docs/SignRequest.md | 2 +- signrequest_python_client/models/sign_request.py | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/SignRequest.md b/docs/SignRequest.md index c09a48f..6cd76d4 100644 --- a/docs/SignRequest.md +++ b/docs/SignRequest.md @@ -22,7 +22,7 @@ Name | Type | Description | Notes **signers** | [**list[Signer]**](Signer.md) | | **uuid** | **str** | | [optional] **url** | **str** | | [optional] -**document** | **str** | | [optional] +**document** | **str** | | **integration** | **str** | | [optional] **integration_data** | **str** | | [optional] diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py index afa2c77..f069864 100644 --- a/signrequest_python_client/models/sign_request.py +++ b/signrequest_python_client/models/sign_request.py @@ -147,8 +147,7 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.uuid = uuid if url is not None: self.url = url - if document is not None: - self.document = document + self.document = document if integration is not None: self.integration = integration if integration_data is not None: @@ -623,6 +622,8 @@ def document(self, document): :param document: The document of this SignRequest. # noqa: E501 :type: str """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 self._document = document From fd24e936b979b56e662d25ae676b7b083c5e02ab Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Tue, 23 Oct 2018 23:10:12 +0200 Subject: [PATCH 15/18] Update signrequests_resend_signrequest_email and signrequests_cancel_signrequest to use expect inline response, instead of SignRequest object, misc schema changes --- README.md | 2 + docs/Document.md | 2 +- docs/DocumentAttachment.md | 2 +- docs/DocumentSearch.md | 2 +- docs/DocumentsSearchApi.md | 4 +- docs/InlineResponse201.md | 11 ++ docs/InlineResponse2011.md | 10 ++ docs/SignrequestsApi.md | 8 +- signrequest_python_client/__init__.py | 2 + .../api/documents_search_api.py | 4 +- .../api/signrequests_api.py | 12 +- signrequest_python_client/models/__init__.py | 2 + signrequest_python_client/models/document.py | 6 +- .../models/document_attachment.py | 5 +- .../models/document_search.py | 4 +- signrequest_python_client/models/event.py | 2 +- .../models/inline_response_201.py | 146 ++++++++++++++++++ .../models/inline_response_201_1.py | 119 ++++++++++++++ .../models/webhook_subscription.py | 2 +- test/test_inline_response_201.py | 40 +++++ test/test_inline_response_201_1.py | 40 +++++ 21 files changed, 399 insertions(+), 26 deletions(-) create mode 100644 docs/InlineResponse201.md create mode 100644 docs/InlineResponse2011.md create mode 100644 signrequest_python_client/models/inline_response_201.py create mode 100644 signrequest_python_client/models/inline_response_201_1.py create mode 100644 test/test_inline_response_201.py create mode 100644 test/test_inline_response_201_1.py diff --git a/README.md b/README.md index ab5e8d5..1499fc6 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,8 @@ Class | Method | HTTP request | Description - [InlineResponse2007](docs/InlineResponse2007.md) - [InlineResponse2008](docs/InlineResponse2008.md) - [InlineResponse2009](docs/InlineResponse2009.md) + - [InlineResponse201](docs/InlineResponse201.md) + - [InlineResponse2011](docs/InlineResponse2011.md) - [InlineSignRequest](docs/InlineSignRequest.md) - [InlineTeam](docs/InlineTeam.md) - [InlineTeamMember](docs/InlineTeamMember.md) diff --git a/docs/Document.md b/docs/Document.md index cd6afe9..3ac870c 100644 --- a/docs/Document.md +++ b/docs/Document.md @@ -21,7 +21,7 @@ Name | Type | Description | Notes **file_from_sf** | [**FileFromSf**](FileFromSf.md) | | [optional] **auto_delete_days** | **int** | Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted | [optional] **pdf** | **str** | Temporary URL to signed document as PDF, expires in five minutes | [optional] -**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] +**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired | [optional] **signrequest** | [**InlineSignRequest**](InlineSignRequest.md) | | [optional] **api_used** | **bool** | Indicates whether document was created using the API | [optional] **security_hash** | **str** | SHA256 hash of PDF contents | [optional] diff --git a/docs/DocumentAttachment.md b/docs/DocumentAttachment.md index e593c84..f7d1f15 100644 --- a/docs/DocumentAttachment.md +++ b/docs/DocumentAttachment.md @@ -10,7 +10,7 @@ Name | Type | Description | Notes **file_from_content** | **str** | Base64 encoded document content | [optional] **file_from_content_name** | **str** | Filename, including extension. Required when using `file_from_content`. | [optional] **file_from_url** | **str** | Publicly accessible URL of document to be downloaded by SignRequest | [optional] -**document** | **str** | | [optional] +**document** | **str** | | [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/docs/DocumentSearch.md b/docs/DocumentSearch.md index 4ab4448..61f6faf 100644 --- a/docs/DocumentSearch.md +++ b/docs/DocumentSearch.md @@ -3,7 +3,7 @@ ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] +**status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired | [optional] **name** | **str** | Defaults to filename | [optional] **who** | **str** | | **nr_extra_docs** | **int** | | diff --git a/docs/DocumentsSearchApi.md b/docs/DocumentsSearchApi.md index 3671fb8..735d515 100644 --- a/docs/DocumentsSearchApi.md +++ b/docs/DocumentsSearchApi.md @@ -36,7 +36,7 @@ autocomplete = 'autocomplete_example' # str | Partial search query (optional) name = 'name_example' # str | Document name (optional) subdomain = 'subdomain_example' # str | (optional) signer_emails = 'signer_emails_example' # str | Email needed to sign/approve (optional) -status = 'status_example' # str | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending (optional) +status = 'status_example' # str | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired (optional) who = 'who_example' # str | `m`: only me, `mo`: me and others, `o`: only others (optional) format = 'format_example' # str | Export format, can be `json` (default), `csv`, or `xls` (optional) signer_data = 8.14 # float | Set to `1` to export with each signer on a separate row (optional) @@ -60,7 +60,7 @@ Name | Type | Description | Notes **name** | **str**| Document name | [optional] **subdomain** | **str**| | [optional] **signer_emails** | **str**| Email needed to sign/approve | [optional] - **status** | **str**| `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending | [optional] + **status** | **str**| `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired | [optional] **who** | **str**| `m`: only me, `mo`: me and others, `o`: only others | [optional] **format** | **str**| Export format, can be `json` (default), `csv`, or `xls` | [optional] **signer_data** | **float**| Set to `1` to export with each signer on a separate row | [optional] diff --git a/docs/InlineResponse201.md b/docs/InlineResponse201.md new file mode 100644 index 0000000..a06e82a --- /dev/null +++ b/docs/InlineResponse201.md @@ -0,0 +1,11 @@ +# InlineResponse201 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**cancelled** | **bool** | | +**detail** | **str** | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/InlineResponse2011.md b/docs/InlineResponse2011.md new file mode 100644 index 0000000..fb48f1d --- /dev/null +++ b/docs/InlineResponse2011.md @@ -0,0 +1,10 @@ +# InlineResponse2011 + +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**detail** | **str** | | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/SignrequestsApi.md b/docs/SignrequestsApi.md index 34d886a..f20c62f 100644 --- a/docs/SignrequestsApi.md +++ b/docs/SignrequestsApi.md @@ -12,7 +12,7 @@ Method | HTTP request | Description # **signrequests_cancel_signrequest** -> SignRequest signrequests_cancel_signrequest(uuid) +> InlineResponse201 signrequests_cancel_signrequest(uuid) Cancel a SignRequest @@ -51,7 +51,7 @@ Name | Type | Description | Notes ### Return type -[**SignRequest**](SignRequest.md) +[**InlineResponse201**](InlineResponse201.md) ### Authorization @@ -230,7 +230,7 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **signrequests_resend_signrequest_email** -> SignRequest signrequests_resend_signrequest_email(uuid) +> InlineResponse2011 signrequests_resend_signrequest_email(uuid) Resend a SignRequest @@ -269,7 +269,7 @@ Name | Type | Description | Notes ### Return type -[**SignRequest**](SignRequest.md) +[**InlineResponse2011**](InlineResponse2011.md) ### Authorization diff --git a/signrequest_python_client/__init__.py b/signrequest_python_client/__init__.py index 7af77b1..d5f23b6 100644 --- a/signrequest_python_client/__init__.py +++ b/signrequest_python_client/__init__.py @@ -52,6 +52,8 @@ from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_python_client.models.inline_response_201 import InlineResponse201 +from signrequest_python_client.models.inline_response_201_1 import InlineResponse2011 from signrequest_python_client.models.inline_sign_request import InlineSignRequest from signrequest_python_client.models.inline_team import InlineTeam from signrequest_python_client.models.inline_team_member import InlineTeamMember diff --git a/signrequest_python_client/api/documents_search_api.py b/signrequest_python_client/api/documents_search_api.py index bdcca7b..eace5f3 100644 --- a/signrequest_python_client/api/documents_search_api.py +++ b/signrequest_python_client/api/documents_search_api.py @@ -50,7 +50,7 @@ def documents_search_list(self, **kwargs): # noqa: E501 :param str name: Document name :param str subdomain: :param str signer_emails: Email needed to sign/approve - :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired :param str who: `m`: only me, `mo`: me and others, `o`: only others :param str format: Export format, can be `json` (default), `csv`, or `xls` :param float signer_data: Set to `1` to export with each signer on a separate row @@ -82,7 +82,7 @@ def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 :param str name: Document name :param str subdomain: :param str signer_emails: Email needed to sign/approve - :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired :param str who: `m`: only me, `mo`: me and others, `o`: only others :param str format: Export format, can be `json` (default), `csv`, or `xls` :param float signer_data: Set to `1` to export with each signer on a separate row diff --git a/signrequest_python_client/api/signrequests_api.py b/signrequest_python_client/api/signrequests_api.py index 0938259..3d43314 100644 --- a/signrequest_python_client/api/signrequests_api.py +++ b/signrequest_python_client/api/signrequests_api.py @@ -44,7 +44,7 @@ def signrequests_cancel_signrequest(self, uuid, **kwargs): # noqa: E501 :param async bool :param str uuid: (required) - :return: SignRequest + :return: InlineResponse201 If the method is called asynchronously, returns the request thread. """ @@ -66,7 +66,7 @@ def signrequests_cancel_signrequest_with_http_info(self, uuid, **kwargs): # noq :param async bool :param str uuid: (required) - :return: SignRequest + :return: InlineResponse201 If the method is called asynchronously, returns the request thread. """ @@ -124,7 +124,7 @@ def signrequests_cancel_signrequest_with_http_info(self, uuid, **kwargs): # noq body=body_params, post_params=form_params, files=local_var_files, - response_type='SignRequest', # noqa: E501 + response_type='InlineResponse201', # noqa: E501 auth_settings=auth_settings, async=params.get('async'), _return_http_data_only=params.get('_return_http_data_only'), @@ -448,7 +448,7 @@ def signrequests_resend_signrequest_email(self, uuid, **kwargs): # noqa: E501 :param async bool :param str uuid: (required) - :return: SignRequest + :return: InlineResponse2011 If the method is called asynchronously, returns the request thread. """ @@ -470,7 +470,7 @@ def signrequests_resend_signrequest_email_with_http_info(self, uuid, **kwargs): :param async bool :param str uuid: (required) - :return: SignRequest + :return: InlineResponse2011 If the method is called asynchronously, returns the request thread. """ @@ -528,7 +528,7 @@ def signrequests_resend_signrequest_email_with_http_info(self, uuid, **kwargs): body=body_params, post_params=form_params, files=local_var_files, - response_type='SignRequest', # noqa: E501 + response_type='InlineResponse2011', # noqa: E501 auth_settings=auth_settings, async=params.get('async'), _return_http_data_only=params.get('_return_http_data_only'), diff --git a/signrequest_python_client/models/__init__.py b/signrequest_python_client/models/__init__.py index f3731e2..c21ab44 100644 --- a/signrequest_python_client/models/__init__.py +++ b/signrequest_python_client/models/__init__.py @@ -35,6 +35,8 @@ from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_python_client.models.inline_response_201 import InlineResponse201 +from signrequest_python_client.models.inline_response_201_1 import InlineResponse2011 from signrequest_python_client.models.inline_sign_request import InlineSignRequest from signrequest_python_client.models.inline_team import InlineTeam from signrequest_python_client.models.inline_team_member import InlineTeamMember diff --git a/signrequest_python_client/models/document.py b/signrequest_python_client/models/document.py index abad23e..3a1871b 100644 --- a/signrequest_python_client/models/document.py +++ b/signrequest_python_client/models/document.py @@ -593,7 +593,7 @@ def pdf(self, pdf): def status(self): """Gets the status of this Document. # noqa: E501 - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 :return: The status of this Document. # noqa: E501 :rtype: str @@ -604,12 +604,12 @@ def status(self): def status(self, status): """Sets the status of this Document. - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 :param status: The status of this Document. # noqa: E501 :type: str """ - allowed_values = ["co", "ne", "se", "vi", "si", "do", "sd", "ca", "de", "ec", "es"] # noqa: E501 + allowed_values = ["co", "ne", "se", "vi", "si", "do", "sd", "ca", "de", "ec", "es", "xp"] # noqa: E501 if status not in allowed_values: raise ValueError( "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 diff --git a/signrequest_python_client/models/document_attachment.py b/signrequest_python_client/models/document_attachment.py index 2129f0a..198b560 100644 --- a/signrequest_python_client/models/document_attachment.py +++ b/signrequest_python_client/models/document_attachment.py @@ -79,8 +79,7 @@ def __init__(self, url=None, uuid=None, name=None, file=None, file_from_content= self.file_from_content_name = file_from_content_name if file_from_url is not None: self.file_from_url = file_from_url - if document is not None: - self.document = document + self.document = document @property def url(self): @@ -263,6 +262,8 @@ def document(self, document): :param document: The document of this DocumentAttachment. # noqa: E501 :type: str """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 self._document = document diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py index 82c8a1e..cfb5421 100644 --- a/signrequest_python_client/models/document_search.py +++ b/signrequest_python_client/models/document_search.py @@ -117,7 +117,7 @@ def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_em def status(self): """Gets the status of this DocumentSearch. # noqa: E501 - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 :return: The status of this DocumentSearch. # noqa: E501 :rtype: str @@ -128,7 +128,7 @@ def status(self): def status(self, status): """Sets the status of this DocumentSearch. - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending # noqa: E501 + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 :param status: The status of this DocumentSearch. # noqa: E501 :type: str diff --git a/signrequest_python_client/models/event.py b/signrequest_python_client/models/event.py index 4439605..ef7cfb6 100644 --- a/signrequest_python_client/models/event.py +++ b/signrequest_python_client/models/event.py @@ -158,7 +158,7 @@ def event_type(self, event_type): :param event_type: The event_type of this Event. # noqa: E501 :type: str """ - allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 if event_type not in allowed_values: raise ValueError( "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 diff --git a/signrequest_python_client/models/inline_response_201.py b/signrequest_python_client/models/inline_response_201.py new file mode 100644 index 0000000..9864d76 --- /dev/null +++ b/signrequest_python_client/models/inline_response_201.py @@ -0,0 +1,146 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineResponse201(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'cancelled': 'bool', + 'detail': 'str' + } + + attribute_map = { + 'cancelled': 'cancelled', + 'detail': 'detail' + } + + def __init__(self, cancelled=None, detail=None): # noqa: E501 + """InlineResponse201 - a model defined in Swagger""" # noqa: E501 + + self._cancelled = None + self._detail = None + self.discriminator = None + + self.cancelled = cancelled + self.detail = detail + + @property + def cancelled(self): + """Gets the cancelled of this InlineResponse201. # noqa: E501 + + + :return: The cancelled of this InlineResponse201. # noqa: E501 + :rtype: bool + """ + return self._cancelled + + @cancelled.setter + def cancelled(self, cancelled): + """Sets the cancelled of this InlineResponse201. + + + :param cancelled: The cancelled of this InlineResponse201. # noqa: E501 + :type: bool + """ + if cancelled is None: + raise ValueError("Invalid value for `cancelled`, must not be `None`") # noqa: E501 + + self._cancelled = cancelled + + @property + def detail(self): + """Gets the detail of this InlineResponse201. # noqa: E501 + + + :return: The detail of this InlineResponse201. # noqa: E501 + :rtype: str + """ + return self._detail + + @detail.setter + def detail(self, detail): + """Sets the detail of this InlineResponse201. + + + :param detail: The detail of this InlineResponse201. # noqa: E501 + :type: str + """ + if detail is None: + raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 + allowed_values = ["OK"] # noqa: E501 + if detail not in allowed_values: + raise ValueError( + "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 + .format(detail, allowed_values) + ) + + self._detail = detail + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse201): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/inline_response_201_1.py b/signrequest_python_client/models/inline_response_201_1.py new file mode 100644 index 0000000..3ee35ef --- /dev/null +++ b/signrequest_python_client/models/inline_response_201_1.py @@ -0,0 +1,119 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineResponse2011(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'detail': 'str' + } + + attribute_map = { + 'detail': 'detail' + } + + def __init__(self, detail=None): # noqa: E501 + """InlineResponse2011 - a model defined in Swagger""" # noqa: E501 + + self._detail = None + self.discriminator = None + + self.detail = detail + + @property + def detail(self): + """Gets the detail of this InlineResponse2011. # noqa: E501 + + + :return: The detail of this InlineResponse2011. # noqa: E501 + :rtype: str + """ + return self._detail + + @detail.setter + def detail(self, detail): + """Sets the detail of this InlineResponse2011. + + + :param detail: The detail of this InlineResponse2011. # noqa: E501 + :type: str + """ + if detail is None: + raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 + allowed_values = ["OK"] # noqa: E501 + if detail not in allowed_values: + raise ValueError( + "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 + .format(detail, allowed_values) + ) + + self._detail = detail + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2011): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_python_client/models/webhook_subscription.py b/signrequest_python_client/models/webhook_subscription.py index 209cbdd..bcf0a49 100644 --- a/signrequest_python_client/models/webhook_subscription.py +++ b/signrequest_python_client/models/webhook_subscription.py @@ -164,7 +164,7 @@ def event_type(self, event_type): """ if event_type is None: raise ValueError("Invalid value for `event_type`, must not be `None`") # noqa: E501 - allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 if event_type not in allowed_values: raise ValueError( "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 diff --git a/test/test_inline_response_201.py b/test/test_inline_response_201.py new file mode 100644 index 0000000..9642b19 --- /dev/null +++ b/test/test_inline_response_201.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_201 import InlineResponse201 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse201(unittest.TestCase): + """InlineResponse201 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse201(self): + """Test InlineResponse201""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_201.InlineResponse201() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() diff --git a/test/test_inline_response_201_1.py b/test/test_inline_response_201_1.py new file mode 100644 index 0000000..9ff84e8 --- /dev/null +++ b/test/test_inline_response_201_1.py @@ -0,0 +1,40 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import unittest + +import signrequest_python_client +from signrequest_python_client.models.inline_response_201_1 import InlineResponse2011 # noqa: E501 +from signrequest_python_client.rest import ApiException + + +class TestInlineResponse2011(unittest.TestCase): + """InlineResponse2011 unit test stubs""" + + def setUp(self): + pass + + def tearDown(self): + pass + + def testInlineResponse2011(self): + """Test InlineResponse2011""" + # FIXME: construct object with mandatory attributes with example values + # model = signrequest_python_client.models.inline_response_201_1.InlineResponse2011() # noqa: E501 + pass + + +if __name__ == '__main__': + unittest.main() From 0d4f945600d9d53cf526f2ad6e01f9afac35f100 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Wed, 24 Oct 2018 15:27:42 +0200 Subject: [PATCH 16/18] Make signrequest on Document read-only --- docs/Document.md | 1 - docs/InlineSignRequest.md | 4 +-- signrequest_python_client/models/document.py | 29 +------------------ .../models/inline_sign_request.py | 26 ++++++++--------- 4 files changed, 15 insertions(+), 45 deletions(-) diff --git a/docs/Document.md b/docs/Document.md index 3ac870c..0ec5357 100644 --- a/docs/Document.md +++ b/docs/Document.md @@ -22,7 +22,6 @@ Name | Type | Description | Notes **auto_delete_days** | **int** | Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted | [optional] **pdf** | **str** | Temporary URL to signed document as PDF, expires in five minutes | [optional] **status** | **str** | `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired | [optional] -**signrequest** | [**InlineSignRequest**](InlineSignRequest.md) | | [optional] **api_used** | **bool** | Indicates whether document was created using the API | [optional] **security_hash** | **str** | SHA256 hash of PDF contents | [optional] **attachments** | [**list[DocumentAttachment]**](DocumentAttachment.md) | | [optional] diff --git a/docs/InlineSignRequest.md b/docs/InlineSignRequest.md index 048d02f..930c4a9 100644 --- a/docs/InlineSignRequest.md +++ b/docs/InlineSignRequest.md @@ -3,7 +3,7 @@ ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**from_email** | **str** | Email of user sending the SignRequest (must be a validated email) | +**from_email** | **str** | Email of user sending the SignRequest (must be a validated email) | [optional] **from_email_name** | **str** | Name to be used in the `From` email header, e.g. `{from_email_name} <no-reply@signrequest.com>` | [optional] **is_being_prepared** | **bool** | Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) | [optional] **prepare_url** | **str** | | [optional] @@ -19,7 +19,7 @@ Name | Type | Description | Notes **message** | **str** | Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` | [optional] **who** | **str** | `m`: only me, `mo`: me and others, `o`: only others | [optional] **send_reminders** | **bool** | Automatically remind signers to sign a document | [optional] -**signers** | [**list[Signer]**](Signer.md) | | +**signers** | [**list[Signer]**](Signer.md) | | [optional] **uuid** | **str** | | [optional] [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/signrequest_python_client/models/document.py b/signrequest_python_client/models/document.py index 3a1871b..1f51ba0 100644 --- a/signrequest_python_client/models/document.py +++ b/signrequest_python_client/models/document.py @@ -20,7 +20,6 @@ from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: F401,E501 from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 -from signrequest_python_client.models.inline_sign_request import InlineSignRequest # noqa: F401,E501 from signrequest_python_client.models.user import User # noqa: F401,E501 @@ -57,7 +56,6 @@ class Document(object): 'auto_delete_days': 'int', 'pdf': 'str', 'status': 'str', - 'signrequest': 'InlineSignRequest', 'api_used': 'bool', 'security_hash': 'str', 'attachments': 'list[DocumentAttachment]', @@ -84,14 +82,13 @@ class Document(object): 'auto_delete_days': 'auto_delete_days', 'pdf': 'pdf', 'status': 'status', - 'signrequest': 'signrequest', 'api_used': 'api_used', 'security_hash': 'security_hash', 'attachments': 'attachments', 'auto_delete_after': 'auto_delete_after' } - def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None, pdf=None, status=None, signrequest=None, api_used=None, security_hash=None, attachments=None, auto_delete_after=None): # noqa: E501 + def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None, pdf=None, status=None, api_used=None, security_hash=None, attachments=None, auto_delete_after=None): # noqa: E501 """Document - a model defined in Swagger""" # noqa: E501 self._url = None @@ -113,7 +110,6 @@ def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, self._auto_delete_days = None self._pdf = None self._status = None - self._signrequest = None self._api_used = None self._security_hash = None self._attachments = None @@ -158,8 +154,6 @@ def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, self.pdf = pdf if status is not None: self.status = status - if signrequest is not None: - self.signrequest = signrequest if api_used is not None: self.api_used = api_used if security_hash is not None: @@ -618,27 +612,6 @@ def status(self, status): self._status = status - @property - def signrequest(self): - """Gets the signrequest of this Document. # noqa: E501 - - - :return: The signrequest of this Document. # noqa: E501 - :rtype: InlineSignRequest - """ - return self._signrequest - - @signrequest.setter - def signrequest(self, signrequest): - """Sets the signrequest of this Document. - - - :param signrequest: The signrequest of this Document. # noqa: E501 - :type: InlineSignRequest - """ - - self._signrequest = signrequest - @property def api_used(self): """Gets the api_used of this Document. # noqa: E501 diff --git a/signrequest_python_client/models/inline_sign_request.py b/signrequest_python_client/models/inline_sign_request.py index 24b2505..396efa1 100644 --- a/signrequest_python_client/models/inline_sign_request.py +++ b/signrequest_python_client/models/inline_sign_request.py @@ -98,7 +98,8 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self._uuid = None self.discriminator = None - self.from_email = from_email + if from_email is not None: + self.from_email = from_email if from_email_name is not None: self.from_email_name = from_email_name if is_being_prepared is not None: @@ -129,7 +130,8 @@ def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None self.who = who if send_reminders is not None: self.send_reminders = send_reminders - self.signers = signers + if signers is not None: + self.signers = signers if uuid is not None: self.uuid = uuid @@ -153,10 +155,6 @@ def from_email(self, from_email): :param from_email: The from_email of this InlineSignRequest. # noqa: E501 :type: str """ - if from_email is None: - raise ValueError("Invalid value for `from_email`, must not be `None`") # noqa: E501 - if from_email is not None and len(from_email) > 255: - raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 if from_email is not None and len(from_email) < 1: raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 @@ -182,8 +180,8 @@ def from_email_name(self, from_email_name): :param from_email_name: The from_email_name of this InlineSignRequest. # noqa: E501 :type: str """ - if from_email_name is not None and len(from_email_name) > 255: - raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + if from_email_name is not None and len(from_email_name) < 1: + raise ValueError("Invalid value for `from_email_name`, length must be greater than or equal to `1`") # noqa: E501 self._from_email_name = from_email_name @@ -253,8 +251,8 @@ def redirect_url(self, redirect_url): :param redirect_url: The redirect_url of this InlineSignRequest. # noqa: E501 :type: str """ - if redirect_url is not None and len(redirect_url) > 2100: - raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + if redirect_url is not None and len(redirect_url) < 1: + raise ValueError("Invalid value for `redirect_url`, length must be greater than or equal to `1`") # noqa: E501 self._redirect_url = redirect_url @@ -437,8 +435,8 @@ def subject(self, subject): :param subject: The subject of this InlineSignRequest. # noqa: E501 :type: str """ - if subject is not None and len(subject) > 512: - raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + if subject is not None and len(subject) < 1: + raise ValueError("Invalid value for `subject`, length must be greater than or equal to `1`") # noqa: E501 self._subject = subject @@ -462,6 +460,8 @@ def message(self, message): :param message: The message of this InlineSignRequest. # noqa: E501 :type: str """ + if message is not None and len(message) < 1: + raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 self._message = message @@ -535,8 +535,6 @@ def signers(self, signers): :param signers: The signers of this InlineSignRequest. # noqa: E501 :type: list[Signer] """ - if signers is None: - raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 self._signers = signers From 9b8122d7e85f74f9e25539b03e3e940dc0817cf8 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Thu, 25 Oct 2018 16:19:56 +0200 Subject: [PATCH 17/18] Update README to use create document example, rename signrequest-python-client to signrequest-client --- README.md | 27 +- docs/ApiTokensApi.md | 36 +- docs/DocumentAttachmentsApi.md | 31 +- docs/DocumentsApi.md | 36 +- docs/DocumentsSearchApi.md | 10 +- docs/EventsApi.md | 18 +- docs/SignrequestQuickCreateApi.md | 12 +- docs/SignrequestsApi.md | 44 +- docs/TeamMembersApi.md | 18 +- docs/TeamsApi.md | 48 +- docs/TemplatesApi.md | 18 +- docs/WebhooksApi.md | 56 +- setup.py | 4 +- signrequest_client/__init__.py | 73 ++ signrequest_client/api/__init__.py | 16 + signrequest_client/api/api_tokens_api.py | 430 +++++++ .../api/document_attachments_api.py | 343 ++++++ signrequest_client/api/documents_api.py | 466 +++++++ .../api/documents_search_api.py | 169 +++ signrequest_client/api/events_api.py | 284 +++++ .../api/signrequest_quick_create_api.py | 133 ++ signrequest_client/api/signrequests_api.py | 537 ++++++++ signrequest_client/api/team_members_api.py | 256 ++++ signrequest_client/api/teams_api.py | 545 ++++++++ signrequest_client/api/templates_api.py | 232 ++++ signrequest_client/api/webhooks_api.py | 644 ++++++++++ signrequest_client/api_client.py | 621 ++++++++++ signrequest_client/configuration.py | 247 ++++ signrequest_client/models/__init__.py | 56 + signrequest_client/models/auth_token.py | 251 ++++ signrequest_client/models/document.py | 748 +++++++++++ .../models/document_attachment.py | 311 +++++ signrequest_client/models/document_search.py | 504 ++++++++ .../models/document_signer_template_conf.py | 278 +++++ signrequest_client/models/event.py | 337 +++++ signrequest_client/models/file_from_sf.py | 144 +++ ...inline_document_signer_integration_data.py | 144 +++ .../models/inline_integration_data.py | 144 +++ .../models/inline_prefill_tags.py | 192 +++ .../models/inline_response_200.py | 194 +++ .../models/inline_response_200_1.py | 194 +++ .../models/inline_response_200_2.py | 194 +++ .../models/inline_response_200_3.py | 194 +++ .../models/inline_response_200_4.py | 194 +++ .../models/inline_response_200_5.py | 194 +++ .../models/inline_response_200_6.py | 194 +++ .../models/inline_response_200_7.py | 194 +++ .../models/inline_response_200_8.py | 194 +++ .../models/inline_response_200_9.py | 194 +++ .../models/inline_response_201.py | 146 +++ .../models/inline_response_201_1.py | 119 ++ .../models/inline_sign_request.py | 605 +++++++++ signrequest_client/models/inline_team.py | 170 +++ .../models/inline_team_member.py | 246 ++++ signrequest_client/models/invite_member.py | 167 +++ signrequest_client/models/placeholder.py | 306 +++++ .../models/required_attachment.py | 145 +++ signrequest_client/models/sign_request.py | 719 +++++++++++ .../models/sign_request_quick_create.py | 1093 +++++++++++++++++ signrequest_client/models/signer.py | 985 +++++++++++++++ .../models/signer_attachment.py | 198 +++ signrequest_client/models/signer_inputs.py | 279 +++++ signrequest_client/models/signing_log.py | 144 +++ signrequest_client/models/team.py | 312 +++++ signrequest_client/models/team_member.py | 246 ++++ signrequest_client/models/template.py | 259 ++++ signrequest_client/models/user.py | 201 +++ .../models/webhook_subscription.py | 292 +++++ signrequest_client/rest.py | 323 +++++ signrequest_python_client/__init__.py | 73 -- signrequest_python_client/api/__init__.py | 16 - .../api/api_tokens_api.py | 430 ------- .../api/document_attachments_api.py | 343 ------ .../api/documents_api.py | 466 ------- .../api/documents_search_api.py | 169 --- signrequest_python_client/api/events_api.py | 284 ----- .../api/signrequest_quick_create_api.py | 133 -- .../api/signrequests_api.py | 537 -------- .../api/team_members_api.py | 256 ---- signrequest_python_client/api/teams_api.py | 545 -------- .../api/templates_api.py | 232 ---- signrequest_python_client/api/webhooks_api.py | 644 ---------- signrequest_python_client/api_client.py | 621 ---------- signrequest_python_client/configuration.py | 247 ---- signrequest_python_client/models/__init__.py | 56 - .../models/auth_token.py | 251 ---- signrequest_python_client/models/document.py | 748 ----------- .../models/document_attachment.py | 311 ----- .../models/document_search.py | 504 -------- .../models/document_signer_template_conf.py | 278 ----- signrequest_python_client/models/event.py | 337 ----- .../models/file_from_sf.py | 144 --- ...inline_document_signer_integration_data.py | 144 --- .../models/inline_integration_data.py | 144 --- .../models/inline_prefill_tags.py | 192 --- .../models/inline_response_200.py | 194 --- .../models/inline_response_200_1.py | 194 --- .../models/inline_response_200_2.py | 194 --- .../models/inline_response_200_3.py | 194 --- .../models/inline_response_200_4.py | 194 --- .../models/inline_response_200_5.py | 194 --- .../models/inline_response_200_6.py | 194 --- .../models/inline_response_200_7.py | 194 --- .../models/inline_response_200_8.py | 194 --- .../models/inline_response_200_9.py | 194 --- .../models/inline_response_201.py | 146 --- .../models/inline_response_201_1.py | 119 -- .../models/inline_sign_request.py | 605 --------- .../models/inline_team.py | 170 --- .../models/inline_team_member.py | 246 ---- .../models/invite_member.py | 167 --- .../models/placeholder.py | 306 ----- .../models/required_attachment.py | 145 --- .../models/sign_request.py | 719 ----------- .../models/sign_request_quick_create.py | 1093 ----------------- signrequest_python_client/models/signer.py | 985 --------------- .../models/signer_attachment.py | 198 --- .../models/signer_inputs.py | 279 ----- .../models/signing_log.py | 144 --- signrequest_python_client/models/team.py | 312 ----- .../models/team_member.py | 246 ---- signrequest_python_client/models/template.py | 259 ---- signrequest_python_client/models/user.py | 201 --- .../models/webhook_subscription.py | 292 ----- signrequest_python_client/rest.py | 323 ----- test/test_api_tokens_api.py | 2 +- test/test_auth_token.py | 2 +- test/test_document.py | 2 +- test/test_document_attachment.py | 2 +- test/test_document_attachments_api.py | 2 +- test/test_document_search.py | 2 +- test/test_document_signer_template_conf.py | 2 +- test/test_documents_api.py | 2 +- test/test_documents_search_api.py | 2 +- test/test_event.py | 2 +- test/test_events_api.py | 2 +- test/test_file_from_sf.py | 2 +- ...inline_document_signer_integration_data.py | 2 +- test/test_inline_integration_data.py | 2 +- test/test_inline_prefill_tags.py | 2 +- test/test_inline_response_200.py | 2 +- test/test_inline_response_200_1.py | 2 +- test/test_inline_response_200_2.py | 2 +- test/test_inline_response_200_3.py | 2 +- test/test_inline_response_200_4.py | 2 +- test/test_inline_response_200_5.py | 2 +- test/test_inline_response_200_6.py | 2 +- test/test_inline_response_200_7.py | 2 +- test/test_inline_response_200_8.py | 2 +- test/test_inline_response_200_9.py | 2 +- test/test_inline_response_201.py | 2 +- test/test_inline_response_201_1.py | 2 +- test/test_inline_sign_request.py | 2 +- test/test_inline_team.py | 2 +- test/test_inline_team_member.py | 2 +- test/test_invite_member.py | 2 +- test/test_placeholder.py | 2 +- test/test_required_attachment.py | 2 +- test/test_sign_request.py | 2 +- test/test_sign_request_quick_create.py | 2 +- test/test_signer.py | 2 +- test/test_signer_attachment.py | 2 +- test/test_signer_inputs.py | 2 +- test/test_signing_log.py | 2 +- test/test_signrequest_quick_create_api.py | 2 +- test/test_signrequests_api.py | 2 +- test/test_team.py | 2 +- test/test_team_member.py | 2 +- test/test_team_members_api.py | 2 +- test/test_teams_api.py | 2 +- test/test_template.py | 2 +- test/test_templates_api.py | 2 +- test/test_user.py | 2 +- test/test_webhook_subscription.py | 2 +- test/test_webhooks_api.py | 2 +- 175 files changed, 17230 insertions(+), 17228 deletions(-) create mode 100644 signrequest_client/__init__.py create mode 100644 signrequest_client/api/__init__.py create mode 100644 signrequest_client/api/api_tokens_api.py create mode 100644 signrequest_client/api/document_attachments_api.py create mode 100644 signrequest_client/api/documents_api.py create mode 100644 signrequest_client/api/documents_search_api.py create mode 100644 signrequest_client/api/events_api.py create mode 100644 signrequest_client/api/signrequest_quick_create_api.py create mode 100644 signrequest_client/api/signrequests_api.py create mode 100644 signrequest_client/api/team_members_api.py create mode 100644 signrequest_client/api/teams_api.py create mode 100644 signrequest_client/api/templates_api.py create mode 100644 signrequest_client/api/webhooks_api.py create mode 100644 signrequest_client/api_client.py create mode 100644 signrequest_client/configuration.py create mode 100644 signrequest_client/models/__init__.py create mode 100644 signrequest_client/models/auth_token.py create mode 100644 signrequest_client/models/document.py create mode 100644 signrequest_client/models/document_attachment.py create mode 100644 signrequest_client/models/document_search.py create mode 100644 signrequest_client/models/document_signer_template_conf.py create mode 100644 signrequest_client/models/event.py create mode 100644 signrequest_client/models/file_from_sf.py create mode 100644 signrequest_client/models/inline_document_signer_integration_data.py create mode 100644 signrequest_client/models/inline_integration_data.py create mode 100644 signrequest_client/models/inline_prefill_tags.py create mode 100644 signrequest_client/models/inline_response_200.py create mode 100644 signrequest_client/models/inline_response_200_1.py create mode 100644 signrequest_client/models/inline_response_200_2.py create mode 100644 signrequest_client/models/inline_response_200_3.py create mode 100644 signrequest_client/models/inline_response_200_4.py create mode 100644 signrequest_client/models/inline_response_200_5.py create mode 100644 signrequest_client/models/inline_response_200_6.py create mode 100644 signrequest_client/models/inline_response_200_7.py create mode 100644 signrequest_client/models/inline_response_200_8.py create mode 100644 signrequest_client/models/inline_response_200_9.py create mode 100644 signrequest_client/models/inline_response_201.py create mode 100644 signrequest_client/models/inline_response_201_1.py create mode 100644 signrequest_client/models/inline_sign_request.py create mode 100644 signrequest_client/models/inline_team.py create mode 100644 signrequest_client/models/inline_team_member.py create mode 100644 signrequest_client/models/invite_member.py create mode 100644 signrequest_client/models/placeholder.py create mode 100644 signrequest_client/models/required_attachment.py create mode 100644 signrequest_client/models/sign_request.py create mode 100644 signrequest_client/models/sign_request_quick_create.py create mode 100644 signrequest_client/models/signer.py create mode 100644 signrequest_client/models/signer_attachment.py create mode 100644 signrequest_client/models/signer_inputs.py create mode 100644 signrequest_client/models/signing_log.py create mode 100644 signrequest_client/models/team.py create mode 100644 signrequest_client/models/team_member.py create mode 100644 signrequest_client/models/template.py create mode 100644 signrequest_client/models/user.py create mode 100644 signrequest_client/models/webhook_subscription.py create mode 100644 signrequest_client/rest.py delete mode 100644 signrequest_python_client/__init__.py delete mode 100644 signrequest_python_client/api/__init__.py delete mode 100644 signrequest_python_client/api/api_tokens_api.py delete mode 100644 signrequest_python_client/api/document_attachments_api.py delete mode 100644 signrequest_python_client/api/documents_api.py delete mode 100644 signrequest_python_client/api/documents_search_api.py delete mode 100644 signrequest_python_client/api/events_api.py delete mode 100644 signrequest_python_client/api/signrequest_quick_create_api.py delete mode 100644 signrequest_python_client/api/signrequests_api.py delete mode 100644 signrequest_python_client/api/team_members_api.py delete mode 100644 signrequest_python_client/api/teams_api.py delete mode 100644 signrequest_python_client/api/templates_api.py delete mode 100644 signrequest_python_client/api/webhooks_api.py delete mode 100644 signrequest_python_client/api_client.py delete mode 100644 signrequest_python_client/configuration.py delete mode 100644 signrequest_python_client/models/__init__.py delete mode 100644 signrequest_python_client/models/auth_token.py delete mode 100644 signrequest_python_client/models/document.py delete mode 100644 signrequest_python_client/models/document_attachment.py delete mode 100644 signrequest_python_client/models/document_search.py delete mode 100644 signrequest_python_client/models/document_signer_template_conf.py delete mode 100644 signrequest_python_client/models/event.py delete mode 100644 signrequest_python_client/models/file_from_sf.py delete mode 100644 signrequest_python_client/models/inline_document_signer_integration_data.py delete mode 100644 signrequest_python_client/models/inline_integration_data.py delete mode 100644 signrequest_python_client/models/inline_prefill_tags.py delete mode 100644 signrequest_python_client/models/inline_response_200.py delete mode 100644 signrequest_python_client/models/inline_response_200_1.py delete mode 100644 signrequest_python_client/models/inline_response_200_2.py delete mode 100644 signrequest_python_client/models/inline_response_200_3.py delete mode 100644 signrequest_python_client/models/inline_response_200_4.py delete mode 100644 signrequest_python_client/models/inline_response_200_5.py delete mode 100644 signrequest_python_client/models/inline_response_200_6.py delete mode 100644 signrequest_python_client/models/inline_response_200_7.py delete mode 100644 signrequest_python_client/models/inline_response_200_8.py delete mode 100644 signrequest_python_client/models/inline_response_200_9.py delete mode 100644 signrequest_python_client/models/inline_response_201.py delete mode 100644 signrequest_python_client/models/inline_response_201_1.py delete mode 100644 signrequest_python_client/models/inline_sign_request.py delete mode 100644 signrequest_python_client/models/inline_team.py delete mode 100644 signrequest_python_client/models/inline_team_member.py delete mode 100644 signrequest_python_client/models/invite_member.py delete mode 100644 signrequest_python_client/models/placeholder.py delete mode 100644 signrequest_python_client/models/required_attachment.py delete mode 100644 signrequest_python_client/models/sign_request.py delete mode 100644 signrequest_python_client/models/sign_request_quick_create.py delete mode 100644 signrequest_python_client/models/signer.py delete mode 100644 signrequest_python_client/models/signer_attachment.py delete mode 100644 signrequest_python_client/models/signer_inputs.py delete mode 100644 signrequest_python_client/models/signing_log.py delete mode 100644 signrequest_python_client/models/team.py delete mode 100644 signrequest_python_client/models/team_member.py delete mode 100644 signrequest_python_client/models/template.py delete mode 100644 signrequest_python_client/models/user.py delete mode 100644 signrequest_python_client/models/webhook_subscription.py delete mode 100644 signrequest_python_client/rest.py diff --git a/README.md b/README.md index 1499fc6..3d4cd23 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ pip install signrequest_python_client Then import the package: ```python -import signrequest_python_client +import signrequest_client ``` ### Setuptools @@ -31,7 +31,7 @@ python setup.py install --user Then import the package: ```python -import signrequest_python_client +import signrequest_client ``` ## Getting Started @@ -41,24 +41,27 @@ Please follow the [installation procedure](#installation--usage) and then run th ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -signrequest_python_client.configuration = signrequest_python_client.Configuration() -signrequest_python_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY' -signrequest_python_client.configuration.api_key_prefix['Authorization'] = 'Token' +signrequest_client.configuration = signrequest_client.Configuration() +signrequest_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY' +signrequest_client.configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.ApiTokensApi() -data = signrequest_python_client.AuthToken() # AuthToken | +api_instance = signrequest_client.DocumentsApi() +data = signrequest_client.Document( + file_from_url='https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing' +) + try: - # Create an API token - api_response = api_instance.api_tokens_create(data) + # Create a Document + api_response = api_instance.documents_create(data) pprint(api_response) except ApiException as e: - print("Exception when calling ApiTokensApi->api_tokens_create: %s\n" % e) + print("Exception when calling DocumentsApi->documents_create: %s\n" % e) ``` diff --git a/docs/ApiTokensApi.md b/docs/ApiTokensApi.md index 208ae4b..86978ec 100644 --- a/docs/ApiTokensApi.md +++ b/docs/ApiTokensApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.ApiTokensApi +# signrequest_client.ApiTokensApi All URIs are relative to *https://signrequest.com/api/v1* @@ -21,18 +21,18 @@ You can create an API token in the [team api settings page](/#/teams). It is als ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.AuthToken() # AuthToken | +api_instance = signrequest_client.ApiTokensApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.AuthToken() # AuthToken | try: # Create an API token @@ -74,17 +74,17 @@ Delete an API token ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.ApiTokensApi(signrequest_client.ApiClient(configuration)) key = 'key_example' # str | A unique value identifying this api token. try: @@ -126,17 +126,17 @@ Retrieve a list of API tokens ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.ApiTokensApi(signrequest_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) @@ -181,17 +181,17 @@ Retrieve an API token ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.ApiTokensApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.ApiTokensApi(signrequest_client.ApiClient(configuration)) key = 'key_example' # str | A unique value identifying this api token. try: diff --git a/docs/DocumentAttachmentsApi.md b/docs/DocumentAttachmentsApi.md index 7815f7a..8d988e2 100644 --- a/docs/DocumentAttachmentsApi.md +++ b/docs/DocumentAttachmentsApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.DocumentAttachmentsApi +# signrequest_client.DocumentAttachmentsApi All URIs are relative to *https://signrequest.com/api/v1* @@ -20,18 +20,18 @@ Create a Document Attachment ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.DocumentAttachment() # DocumentAttachment | +api_instance = signrequest_client.DocumentAttachmentsApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.DocumentAttachment() # DocumentAttachment | try: # Create a Document Attachment @@ -73,18 +73,17 @@ Retrieve a list of Document Attachments ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' -# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed -# configuration.api_key_prefix['Authorization'] = 'Bearer' +configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentAttachmentsApi(signrequest_client.ApiClient(configuration)) document__uuid = 'document__uuid_example' # str | (optional) document__external_id = 'document__external_id_example' # str | (optional) created = 'created_example' # str | (optional) @@ -135,17 +134,17 @@ Retrieve a Document Attachment ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentAttachmentsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentAttachmentsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: diff --git a/docs/DocumentsApi.md b/docs/DocumentsApi.md index c48bee9..a4032e2 100644 --- a/docs/DocumentsApi.md +++ b/docs/DocumentsApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.DocumentsApi +# signrequest_client.DocumentsApi All URIs are relative to *https://signrequest.com/api/v1* @@ -21,18 +21,18 @@ Create a Document ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.Document() # Document | +api_instance = signrequest_client.DocumentsApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.Document() # Document | try: # Create a Document @@ -74,17 +74,17 @@ Delete a Document ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: @@ -126,17 +126,17 @@ Retrieve a list of Documents ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentsApi(signrequest_client.ApiClient(configuration)) external_id = 'external_id_example' # str | (optional) signrequest__who = 'signrequest__who_example' # str | (optional) signrequest__from_email = 'signrequest__from_email_example' # str | (optional) @@ -199,17 +199,17 @@ Retrieve a Document ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: diff --git a/docs/DocumentsSearchApi.md b/docs/DocumentsSearchApi.md index 735d515..4f4b7ad 100644 --- a/docs/DocumentsSearchApi.md +++ b/docs/DocumentsSearchApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.DocumentsSearchApi +# signrequest_client.DocumentsSearchApi All URIs are relative to *https://signrequest.com/api/v1* @@ -18,17 +18,17 @@ Search interface for fast (autocomplete) searching of documents. This can be us ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.DocumentsSearchApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.DocumentsSearchApi(signrequest_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) q = 'q_example' # str | Normal search query (optional) diff --git a/docs/EventsApi.md b/docs/EventsApi.md index aa10ccb..517c254 100644 --- a/docs/EventsApi.md +++ b/docs/EventsApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.EventsApi +# signrequest_client.EventsApi All URIs are relative to *https://signrequest.com/api/v1* @@ -19,17 +19,17 @@ Retrieve a list of Events ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.EventsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.EventsApi(signrequest_client.ApiClient(configuration)) document__uuid = 'document__uuid_example' # str | (optional) document__external_id = 'document__external_id_example' # str | (optional) document__signrequest__who = 'document__signrequest__who_example' # str | (optional) @@ -100,17 +100,17 @@ Retrieve an Event ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.EventsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.EventsApi(signrequest_client.ApiClient(configuration)) id = 56 # int | A unique integer value identifying this event. try: diff --git a/docs/SignrequestQuickCreateApi.md b/docs/SignrequestQuickCreateApi.md index e6ed862..5192b6b 100644 --- a/docs/SignrequestQuickCreateApi.md +++ b/docs/SignrequestQuickCreateApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.SignrequestQuickCreateApi +# signrequest_client.SignrequestQuickCreateApi All URIs are relative to *https://signrequest.com/api/v1* @@ -18,18 +18,18 @@ Quick create a SignRequest ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestQuickCreateApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.SignRequestQuickCreate() # SignRequestQuickCreate | +api_instance = signrequest_client.SignrequestQuickCreateApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.SignRequestQuickCreate() # SignRequestQuickCreate | try: # Quick create a SignRequest diff --git a/docs/SignrequestsApi.md b/docs/SignrequestsApi.md index f20c62f..da81237 100644 --- a/docs/SignrequestsApi.md +++ b/docs/SignrequestsApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.SignrequestsApi +# signrequest_client.SignrequestsApi All URIs are relative to *https://signrequest.com/api/v1* @@ -22,17 +22,17 @@ Cancel a SignRequest ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.SignrequestsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: @@ -75,18 +75,18 @@ Create a SignRequest ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.SignRequest() # SignRequest | +api_instance = signrequest_client.SignrequestsApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.SignRequest() # SignRequest | try: # Create a SignRequest @@ -128,17 +128,17 @@ Retrieve a list of SignRequests ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.SignrequestsApi(signrequest_client.ApiClient(configuration)) who = 'who_example' # str | (optional) from_email = 'from_email_example' # str | (optional) page = 56 # int | A page number within the paginated result set. (optional) @@ -187,17 +187,17 @@ Retrieve a SignRequest ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.SignrequestsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: @@ -240,17 +240,17 @@ Resend a SignRequest ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.SignrequestsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.SignrequestsApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: diff --git a/docs/TeamMembersApi.md b/docs/TeamMembersApi.md index fab2514..0c51e9f 100644 --- a/docs/TeamMembersApi.md +++ b/docs/TeamMembersApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.TeamMembersApi +# signrequest_client.TeamMembersApi All URIs are relative to *https://signrequest.com/api/v1* @@ -19,17 +19,17 @@ Retrieve a list of Team Members ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamMembersApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamMembersApi(signrequest_client.ApiClient(configuration)) is_active = 'is_active_example' # str | (optional) is_owner = 'is_owner_example' # str | (optional) is_admin = 'is_admin_example' # str | (optional) @@ -86,17 +86,17 @@ Retrieve a Team Member ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamMembersApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamMembersApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: diff --git a/docs/TeamsApi.md b/docs/TeamsApi.md index 482aed2..b744f30 100644 --- a/docs/TeamsApi.md +++ b/docs/TeamsApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.TeamsApi +# signrequest_client.TeamsApi All URIs are relative to *https://signrequest.com/api/v1* @@ -22,18 +22,18 @@ Required fields are **name** and **subdomain** where the subdomain is globally u ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.Team() # Team | +api_instance = signrequest_client.TeamsApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.Team() # Team | try: # Create a Team @@ -75,19 +75,19 @@ Required fields are **name** and **subdomain** where the subdomain is globally u ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamsApi(signrequest_client.ApiClient(configuration)) subdomain = 'subdomain_example' # str | -data = signrequest_python_client.InviteMember() # InviteMember | +data = signrequest_client.InviteMember() # InviteMember | try: # Invite a Team Member @@ -130,17 +130,17 @@ Required fields are **name** and **subdomain** where the subdomain is globally u ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamsApi(signrequest_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) @@ -185,19 +185,19 @@ Required fields are **name** and **subdomain** where the subdomain is globally u ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamsApi(signrequest_client.ApiClient(configuration)) subdomain = 'subdomain_example' # str | -data = signrequest_python_client.Team() # Team | +data = signrequest_client.Team() # Team | try: # Update a Team @@ -240,17 +240,17 @@ Required fields are **name** and **subdomain** where the subdomain is globally u ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TeamsApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TeamsApi(signrequest_client.ApiClient(configuration)) subdomain = 'subdomain_example' # str | try: diff --git a/docs/TemplatesApi.md b/docs/TemplatesApi.md index 04039fd..9192aea 100644 --- a/docs/TemplatesApi.md +++ b/docs/TemplatesApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.TemplatesApi +# signrequest_client.TemplatesApi All URIs are relative to *https://signrequest.com/api/v1* @@ -19,17 +19,17 @@ Retrieve a list of Templates ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TemplatesApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TemplatesApi(signrequest_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) @@ -74,17 +74,17 @@ Retrieve a Template ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.TemplatesApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.TemplatesApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: diff --git a/docs/WebhooksApi.md b/docs/WebhooksApi.md index 7ddfe73..0af3e4c 100644 --- a/docs/WebhooksApi.md +++ b/docs/WebhooksApi.md @@ -1,4 +1,4 @@ -# signrequest_python_client.WebhooksApi +# signrequest_client.WebhooksApi All URIs are relative to *https://signrequest.com/api/v1* @@ -23,18 +23,18 @@ Create a Webhook ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) -data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) +data = signrequest_client.WebhookSubscription() # WebhookSubscription | try: # Create a Webhook @@ -76,17 +76,17 @@ Delete a Webhook ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: @@ -128,17 +128,17 @@ Retrieve a list of Webhooks ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) page = 56 # int | A page number within the paginated result set. (optional) limit = 56 # int | Number of results to return per page. (optional) @@ -183,19 +183,19 @@ Partially update a Webhook ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | -data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | +data = signrequest_client.WebhookSubscription() # WebhookSubscription | try: # Partially update a Webhook @@ -238,17 +238,17 @@ Retrieve a Webhook ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | try: @@ -291,19 +291,19 @@ Update a Webhook ```python from __future__ import print_function import time -import signrequest_python_client -from signrequest_python_client.rest import ApiException +import signrequest_client +from signrequest_client.rest import ApiException from pprint import pprint # Configure API key authorization: Token -configuration = signrequest_python_client.Configuration() +configuration = signrequest_client.Configuration() configuration.api_key['Authorization'] = 'YOUR_API_KEY' configuration.api_key_prefix['Authorization'] = 'Token' # create an instance of the API class -api_instance = signrequest_python_client.WebhooksApi(signrequest_python_client.ApiClient(configuration)) +api_instance = signrequest_client.WebhooksApi(signrequest_client.ApiClient(configuration)) uuid = 'uuid_example' # str | -data = signrequest_python_client.WebhookSubscription() # WebhookSubscription | +data = signrequest_client.WebhookSubscription() # WebhookSubscription | try: # Update a Webhook diff --git a/setup.py b/setup.py index 369112b..33a1e37 100644 --- a/setup.py +++ b/setup.py @@ -14,8 +14,8 @@ from setuptools import setup, find_packages # noqa: H301 import os -NAME = "signrequest-python-client" -VERSION = "2.0.0" +NAME = "signrequest-client" +VERSION = "1.0.0" def read(fname): diff --git a/signrequest_client/__init__.py b/signrequest_client/__init__.py new file mode 100644 index 0000000..fb85ea3 --- /dev/null +++ b/signrequest_client/__init__.py @@ -0,0 +1,73 @@ +# coding: utf-8 + +# flake8: noqa + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +# import apis into sdk package +from signrequest_client.api.api_tokens_api import ApiTokensApi +from signrequest_client.api.document_attachments_api import DocumentAttachmentsApi +from signrequest_client.api.documents_api import DocumentsApi +from signrequest_client.api.documents_search_api import DocumentsSearchApi +from signrequest_client.api.events_api import EventsApi +from signrequest_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi +from signrequest_client.api.signrequests_api import SignrequestsApi +from signrequest_client.api.team_members_api import TeamMembersApi +from signrequest_client.api.teams_api import TeamsApi +from signrequest_client.api.templates_api import TemplatesApi +from signrequest_client.api.webhooks_api import WebhooksApi + +# import ApiClient +from signrequest_client.api_client import ApiClient +from signrequest_client.configuration import Configuration +# import models into sdk package +from signrequest_client.models.auth_token import AuthToken +from signrequest_client.models.document import Document +from signrequest_client.models.document_attachment import DocumentAttachment +from signrequest_client.models.document_search import DocumentSearch +from signrequest_client.models.document_signer_template_conf import DocumentSignerTemplateConf +from signrequest_client.models.event import Event +from signrequest_client.models.file_from_sf import FileFromSf +from signrequest_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData +from signrequest_client.models.inline_integration_data import InlineIntegrationData +from signrequest_client.models.inline_prefill_tags import InlinePrefillTags +from signrequest_client.models.inline_response_200 import InlineResponse200 +from signrequest_client.models.inline_response_200_1 import InlineResponse2001 +from signrequest_client.models.inline_response_200_2 import InlineResponse2002 +from signrequest_client.models.inline_response_200_3 import InlineResponse2003 +from signrequest_client.models.inline_response_200_4 import InlineResponse2004 +from signrequest_client.models.inline_response_200_5 import InlineResponse2005 +from signrequest_client.models.inline_response_200_6 import InlineResponse2006 +from signrequest_client.models.inline_response_200_7 import InlineResponse2007 +from signrequest_client.models.inline_response_200_8 import InlineResponse2008 +from signrequest_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_client.models.inline_response_201 import InlineResponse201 +from signrequest_client.models.inline_response_201_1 import InlineResponse2011 +from signrequest_client.models.inline_sign_request import InlineSignRequest +from signrequest_client.models.inline_team import InlineTeam +from signrequest_client.models.inline_team_member import InlineTeamMember +from signrequest_client.models.invite_member import InviteMember +from signrequest_client.models.placeholder import Placeholder +from signrequest_client.models.required_attachment import RequiredAttachment +from signrequest_client.models.sign_request import SignRequest +from signrequest_client.models.sign_request_quick_create import SignRequestQuickCreate +from signrequest_client.models.signer import Signer +from signrequest_client.models.signer_attachment import SignerAttachment +from signrequest_client.models.signer_inputs import SignerInputs +from signrequest_client.models.signing_log import SigningLog +from signrequest_client.models.team import Team +from signrequest_client.models.team_member import TeamMember +from signrequest_client.models.template import Template +from signrequest_client.models.user import User +from signrequest_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_client/api/__init__.py b/signrequest_client/api/__init__.py new file mode 100644 index 0000000..7e870fa --- /dev/null +++ b/signrequest_client/api/__init__.py @@ -0,0 +1,16 @@ +from __future__ import absolute_import + +# flake8: noqa + +# import apis into api package +from signrequest_client.api.api_tokens_api import ApiTokensApi +from signrequest_client.api.document_attachments_api import DocumentAttachmentsApi +from signrequest_client.api.documents_api import DocumentsApi +from signrequest_client.api.documents_search_api import DocumentsSearchApi +from signrequest_client.api.events_api import EventsApi +from signrequest_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi +from signrequest_client.api.signrequests_api import SignrequestsApi +from signrequest_client.api.team_members_api import TeamMembersApi +from signrequest_client.api.teams_api import TeamsApi +from signrequest_client.api.templates_api import TemplatesApi +from signrequest_client.api.webhooks_api import WebhooksApi diff --git a/signrequest_client/api/api_tokens_api.py b/signrequest_client/api/api_tokens_api.py new file mode 100644 index 0000000..58fdc9a --- /dev/null +++ b/signrequest_client/api/api_tokens_api.py @@ -0,0 +1,430 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class ApiTokensApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def api_tokens_create(self, data, **kwargs): # noqa: E501 + """Create an API token # noqa: E501 + + You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param AuthToken data: (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def api_tokens_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create an API token # noqa: E501 + + You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param AuthToken data: (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `api_tokens_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='AuthToken', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_delete(self, key, **kwargs): # noqa: E501 + """Delete an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_delete(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 + return data + + def api_tokens_delete_with_http_info(self, key, **kwargs): # noqa: E501 + """Delete an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_delete_with_http_info(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['key'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'key' is set + if ('key' not in params or + params['key'] is None): + raise ValueError("Missing the required parameter `key` when calling `api_tokens_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'key' in params: + path_params['key'] = params['key'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/{key}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_list(self, **kwargs): # noqa: E501 + """Retrieve a list of API tokens # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse200 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 + return data + + def api_tokens_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of API tokens # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse200 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse200', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def api_tokens_read(self, key, **kwargs): # noqa: E501 + """Retrieve an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_read(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 + else: + (data) = self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 + return data + + def api_tokens_read_with_http_info(self, key, **kwargs): # noqa: E501 + """Retrieve an API token # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.api_tokens_read_with_http_info(key, async=True) + >>> result = thread.get() + + :param async bool + :param str key: A unique value identifying this api token. (required) + :return: AuthToken + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['key'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method api_tokens_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'key' is set + if ('key' not in params or + params['key'] is None): + raise ValueError("Missing the required parameter `key` when calling `api_tokens_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'key' in params: + path_params['key'] = params['key'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/api-tokens/{key}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='AuthToken', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/document_attachments_api.py b/signrequest_client/api/document_attachments_api.py new file mode 100644 index 0000000..2240157 --- /dev/null +++ b/signrequest_client/api/document_attachments_api.py @@ -0,0 +1,343 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class DocumentAttachmentsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def document_attachments_create(self, data, **kwargs): # noqa: E501 + """Create a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param DocumentAttachment data: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def document_attachments_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param DocumentAttachment data: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `document_attachments_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='DocumentAttachment', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def document_attachments_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Document Attachments # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_list(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str created: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2001 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 + return data + + def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Document Attachments # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str created: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2001 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['document__uuid', 'document__external_id', 'created', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'document__uuid' in params: + query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 + if 'document__external_id' in params: + query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 + if 'created' in params: + query_params.append(('created', params['created'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2001', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def document_attachments_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def document_attachments_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document Attachment # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.document_attachments_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: DocumentAttachment + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method document_attachments_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `document_attachments_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/document-attachments/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='DocumentAttachment', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/documents_api.py b/signrequest_client/api/documents_api.py new file mode 100644 index 0000000..42f9e12 --- /dev/null +++ b/signrequest_client/api/documents_api.py @@ -0,0 +1,466 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class DocumentsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def documents_create(self, data, **kwargs): # noqa: E501 + """Create a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param Document data: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.documents_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def documents_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param Document data: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `documents_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Document', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_delete(self, uuid, **kwargs): # noqa: E501 + """Delete a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_delete(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def documents_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Delete a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_delete_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `documents_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/{uuid}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Documents # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_list(async=True) + >>> result = thread.get() + + :param async bool + :param str external_id: + :param str signrequest__who: + :param str signrequest__from_email: + :param str status: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param str created: + :param str modified: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2003 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.documents_list_with_http_info(**kwargs) # noqa: E501 + return data + + def documents_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Documents # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str external_id: + :param str signrequest__who: + :param str signrequest__from_email: + :param str status: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param str created: + :param str modified: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2003 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['external_id', 'signrequest__who', 'signrequest__from_email', 'status', 'user__email', 'user__first_name', 'user__last_name', 'created', 'modified', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'external_id' in params: + query_params.append(('external_id', params['external_id'])) # noqa: E501 + if 'signrequest__who' in params: + query_params.append(('signrequest__who', params['signrequest__who'])) # noqa: E501 + if 'signrequest__from_email' in params: + query_params.append(('signrequest__from_email', params['signrequest__from_email'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'user__email' in params: + query_params.append(('user__email', params['user__email'])) # noqa: E501 + if 'user__first_name' in params: + query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 + if 'user__last_name' in params: + query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 + if 'created' in params: + query_params.append(('created', params['created'])) # noqa: E501 + if 'modified' in params: + query_params.append(('modified', params['modified'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2003', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def documents_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def documents_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Document # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Document + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `documents_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Document', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/documents_search_api.py b/signrequest_client/api/documents_search_api.py new file mode 100644 index 0000000..9845c90 --- /dev/null +++ b/signrequest_client/api/documents_search_api.py @@ -0,0 +1,169 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class DocumentsSearchApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def documents_search_list(self, **kwargs): # noqa: E501 + """Search documents # noqa: E501 + + Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_search_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :param str q: Normal search query + :param str autocomplete: Partial search query + :param str name: Document name + :param str subdomain: + :param str signer_emails: Email needed to sign/approve + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired + :param str who: `m`: only me, `mo`: me and others, `o`: only others + :param str format: Export format, can be `json` (default), `csv`, or `xls` + :param float signer_data: Set to `1` to export with each signer on a separate row + :return: InlineResponse2002 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.documents_search_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.documents_search_list_with_http_info(**kwargs) # noqa: E501 + return data + + def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 + """Search documents # noqa: E501 + + Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.documents_search_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :param str q: Normal search query + :param str autocomplete: Partial search query + :param str name: Document name + :param str subdomain: + :param str signer_emails: Email needed to sign/approve + :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired + :param str who: `m`: only me, `mo`: me and others, `o`: only others + :param str format: Export format, can be `json` (default), `csv`, or `xls` + :param float signer_data: Set to `1` to export with each signer on a separate row + :return: InlineResponse2002 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit', 'q', 'autocomplete', 'name', 'subdomain', 'signer_emails', 'status', 'who', 'format', 'signer_data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method documents_search_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + if 'q' in params: + query_params.append(('q', params['q'])) # noqa: E501 + if 'autocomplete' in params: + query_params.append(('autocomplete', params['autocomplete'])) # noqa: E501 + if 'name' in params: + query_params.append(('name', params['name'])) # noqa: E501 + if 'subdomain' in params: + query_params.append(('subdomain', params['subdomain'])) # noqa: E501 + if 'signer_emails' in params: + query_params.append(('signer_emails', params['signer_emails'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'who' in params: + query_params.append(('who', params['who'])) # noqa: E501 + if 'format' in params: + query_params.append(('format', params['format'])) # noqa: E501 + if 'signer_data' in params: + query_params.append(('signer_data', params['signer_data'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json', 'text/csv', 'application/vnd.ms-excel']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/documents-search/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2002', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/events_api.py b/signrequest_client/api/events_api.py new file mode 100644 index 0000000..dd15748 --- /dev/null +++ b/signrequest_client/api/events_api.py @@ -0,0 +1,284 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class EventsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def events_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Events # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_list(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str document__signrequest__who: + :param str document__signrequest__from_email: + :param str document__status: + :param str document__user__email: + :param str document__user__first_name: + :param str document__user__last_name: + :param str delivered: + :param str delivered_on: + :param str timestamp: + :param str status: + :param str event_type: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2004 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.events_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.events_list_with_http_info(**kwargs) # noqa: E501 + return data + + def events_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Events # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str document__uuid: + :param str document__external_id: + :param str document__signrequest__who: + :param str document__signrequest__from_email: + :param str document__status: + :param str document__user__email: + :param str document__user__first_name: + :param str document__user__last_name: + :param str delivered: + :param str delivered_on: + :param str timestamp: + :param str status: + :param str event_type: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2004 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['document__uuid', 'document__external_id', 'document__signrequest__who', 'document__signrequest__from_email', 'document__status', 'document__user__email', 'document__user__first_name', 'document__user__last_name', 'delivered', 'delivered_on', 'timestamp', 'status', 'event_type', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method events_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'document__uuid' in params: + query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 + if 'document__external_id' in params: + query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 + if 'document__signrequest__who' in params: + query_params.append(('document__signrequest__who', params['document__signrequest__who'])) # noqa: E501 + if 'document__signrequest__from_email' in params: + query_params.append(('document__signrequest__from_email', params['document__signrequest__from_email'])) # noqa: E501 + if 'document__status' in params: + query_params.append(('document__status', params['document__status'])) # noqa: E501 + if 'document__user__email' in params: + query_params.append(('document__user__email', params['document__user__email'])) # noqa: E501 + if 'document__user__first_name' in params: + query_params.append(('document__user__first_name', params['document__user__first_name'])) # noqa: E501 + if 'document__user__last_name' in params: + query_params.append(('document__user__last_name', params['document__user__last_name'])) # noqa: E501 + if 'delivered' in params: + query_params.append(('delivered', params['delivered'])) # noqa: E501 + if 'delivered_on' in params: + query_params.append(('delivered_on', params['delivered_on'])) # noqa: E501 + if 'timestamp' in params: + query_params.append(('timestamp', params['timestamp'])) # noqa: E501 + if 'status' in params: + query_params.append(('status', params['status'])) # noqa: E501 + if 'event_type' in params: + query_params.append(('event_type', params['event_type'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/events/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2004', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def events_read(self, id, **kwargs): # noqa: E501 + """Retrieve an Event # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_read(id, async=True) + >>> result = thread.get() + + :param async bool + :param int id: A unique integer value identifying this event. (required) + :return: Event + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.events_read_with_http_info(id, **kwargs) # noqa: E501 + else: + (data) = self.events_read_with_http_info(id, **kwargs) # noqa: E501 + return data + + def events_read_with_http_info(self, id, **kwargs): # noqa: E501 + """Retrieve an Event # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.events_read_with_http_info(id, async=True) + >>> result = thread.get() + + :param async bool + :param int id: A unique integer value identifying this event. (required) + :return: Event + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['id'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method events_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'id' is set + if ('id' not in params or + params['id'] is None): + raise ValueError("Missing the required parameter `id` when calling `events_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'id' in params: + path_params['id'] = params['id'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/events/{id}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Event', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/signrequest_quick_create_api.py b/signrequest_client/api/signrequest_quick_create_api.py new file mode 100644 index 0000000..4d3f355 --- /dev/null +++ b/signrequest_client/api/signrequest_quick_create_api.py @@ -0,0 +1,133 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class SignrequestQuickCreateApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def signrequest_quick_create_create(self, data, **kwargs): # noqa: E501 + """Quick create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequest_quick_create_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequestQuickCreate data: (required) + :return: SignRequestQuickCreate + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def signrequest_quick_create_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Quick create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequest_quick_create_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequestQuickCreate data: (required) + :return: SignRequestQuickCreate + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequest_quick_create_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequest_quick_create_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequest-quick-create/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequestQuickCreate', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/signrequests_api.py b/signrequest_client/api/signrequests_api.py new file mode 100644 index 0000000..2528b09 --- /dev/null +++ b/signrequest_client/api/signrequests_api.py @@ -0,0 +1,537 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class SignrequestsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def signrequests_cancel_signrequest(self, uuid, **kwargs): # noqa: E501 + """Cancel a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_cancel_signrequest(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: InlineResponse201 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def signrequests_cancel_signrequest_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Cancel a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_cancel_signrequest_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: InlineResponse201 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_cancel_signrequest" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_cancel_signrequest`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/cancel_signrequest/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse201', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_create(self, data, **kwargs): # noqa: E501 + """Create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def signrequests_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param SignRequest data: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `signrequests_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_list(self, **kwargs): # noqa: E501 + """Retrieve a list of SignRequests # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_list(async=True) + >>> result = thread.get() + + :param async bool + :param str who: + :param str from_email: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2005 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.signrequests_list_with_http_info(**kwargs) # noqa: E501 + return data + + def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of SignRequests # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str who: + :param str from_email: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2005 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['who', 'from_email', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'who' in params: + query_params.append(('who', params['who'])) # noqa: E501 + if 'from_email' in params: + query_params.append(('from_email', params['from_email'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2005', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def signrequests_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: SignRequest + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='SignRequest', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def signrequests_resend_signrequest_email(self, uuid, **kwargs): # noqa: E501 + """Resend a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_resend_signrequest_email(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: InlineResponse2011 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def signrequests_resend_signrequest_email_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Resend a SignRequest # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.signrequests_resend_signrequest_email_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: InlineResponse2011 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method signrequests_resend_signrequest_email" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `signrequests_resend_signrequest_email`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/signrequests/{uuid}/resend_signrequest_email/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2011', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/team_members_api.py b/signrequest_client/api/team_members_api.py new file mode 100644 index 0000000..debe973 --- /dev/null +++ b/signrequest_client/api/team_members_api.py @@ -0,0 +1,256 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class TeamMembersApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def team_members_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Team Members # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_list(async=True) + >>> result = thread.get() + + :param async bool + :param str is_active: + :param str is_owner: + :param str is_admin: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2006 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.team_members_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.team_members_list_with_http_info(**kwargs) # noqa: E501 + return data + + def team_members_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Team Members # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param str is_active: + :param str is_owner: + :param str is_admin: + :param str user__email: + :param str user__first_name: + :param str user__last_name: + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2006 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['is_active', 'is_owner', 'is_admin', 'user__email', 'user__first_name', 'user__last_name', 'page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method team_members_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'is_active' in params: + query_params.append(('is_active', params['is_active'])) # noqa: E501 + if 'is_owner' in params: + query_params.append(('is_owner', params['is_owner'])) # noqa: E501 + if 'is_admin' in params: + query_params.append(('is_admin', params['is_admin'])) # noqa: E501 + if 'user__email' in params: + query_params.append(('user__email', params['user__email'])) # noqa: E501 + if 'user__first_name' in params: + query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 + if 'user__last_name' in params: + query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/team-members/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2006', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def team_members_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Team Member # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: TeamMember + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def team_members_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Team Member # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.team_members_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: TeamMember + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method team_members_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `team_members_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/team-members/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='TeamMember', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/teams_api.py b/signrequest_client/api/teams_api.py new file mode 100644 index 0000000..3834e44 --- /dev/null +++ b/signrequest_client/api/teams_api.py @@ -0,0 +1,545 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class TeamsApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def teams_create(self, data, **kwargs): # noqa: E501 + """Create a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.teams_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def teams_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_invite_member(self, subdomain, data, **kwargs): # noqa: E501 + """Invite a Team Member # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_invite_member(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param InviteMember data: (required) + :return: InviteMember + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 + else: + (data) = self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 + return data + + def teams_invite_member_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 + """Invite a Team Member # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_invite_member_with_http_info(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param InviteMember data: (required) + :return: InviteMember + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_invite_member" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_invite_member`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_invite_member`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/invite_member/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InviteMember', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Teams # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2007 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.teams_list_with_http_info(**kwargs) # noqa: E501 + return data + + def teams_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Teams # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2007 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2007', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_partial_update(self, subdomain, data, **kwargs): # noqa: E501 + """Update a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_partial_update(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 + else: + (data) = self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 + return data + + def teams_partial_update_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 + """Update a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_partial_update_with_http_info(subdomain, data, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :param Team data: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_partial_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_partial_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `teams_partial_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/', 'PATCH', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def teams_read(self, subdomain, **kwargs): # noqa: E501 + """Retrieve a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_read(subdomain, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 + else: + (data) = self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 + return data + + def teams_read_with_http_info(self, subdomain, **kwargs): # noqa: E501 + """Retrieve a Team # noqa: E501 + + Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.teams_read_with_http_info(subdomain, async=True) + >>> result = thread.get() + + :param async bool + :param str subdomain: (required) + :return: Team + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['subdomain'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method teams_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'subdomain' is set + if ('subdomain' not in params or + params['subdomain'] is None): + raise ValueError("Missing the required parameter `subdomain` when calling `teams_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'subdomain' in params: + path_params['subdomain'] = params['subdomain'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/teams/{subdomain}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Team', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/templates_api.py b/signrequest_client/api/templates_api.py new file mode 100644 index 0000000..ade6888 --- /dev/null +++ b/signrequest_client/api/templates_api.py @@ -0,0 +1,232 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class TemplatesApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def templates_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Templates # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2008 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.templates_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.templates_list_with_http_info(**kwargs) # noqa: E501 + return data + + def templates_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Templates # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2008 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method templates_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/templates/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2008', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def templates_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Template # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Template + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def templates_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Template # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.templates_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: Template + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method templates_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `templates_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/templates/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='Template', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api/webhooks_api.py b/signrequest_client/api/webhooks_api.py new file mode 100644 index 0000000..dcfbd0c --- /dev/null +++ b/signrequest_client/api/webhooks_api.py @@ -0,0 +1,644 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import re # noqa: F401 + +# python 2 and python 3 compatibility library +import six + +from signrequest_client.api_client import ApiClient + + +class WebhooksApi(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + Ref: https://github.com/swagger-api/swagger-codegen + """ + + def __init__(self, api_client=None): + if api_client is None: + api_client = ApiClient() + self.api_client = api_client + + def webhooks_create(self, data, **kwargs): # noqa: E501 + """Create a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_create(data, async=True) + >>> result = thread.get() + + :param async bool + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 + return data + + def webhooks_create_with_http_info(self, data, **kwargs): # noqa: E501 + """Create a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_create_with_http_info(data, async=True) + >>> result = thread.get() + + :param async bool + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_create" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_create`") # noqa: E501 + + collection_formats = {} + + path_params = {} + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/', 'POST', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_delete(self, uuid, **kwargs): # noqa: E501 + """Delete a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_delete(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def webhooks_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Delete a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_delete_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: None + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_delete" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_delete`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'DELETE', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type=None, # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_list(self, **kwargs): # noqa: E501 + """Retrieve a list of Webhooks # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_list(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2009 + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_list_with_http_info(**kwargs) # noqa: E501 + else: + (data) = self.webhooks_list_with_http_info(**kwargs) # noqa: E501 + return data + + def webhooks_list_with_http_info(self, **kwargs): # noqa: E501 + """Retrieve a list of Webhooks # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_list_with_http_info(async=True) + >>> result = thread.get() + + :param async bool + :param int page: A page number within the paginated result set. + :param int limit: Number of results to return per page. + :return: InlineResponse2009 + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['page', 'limit'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_list" % key + ) + params[key] = val + del params['kwargs'] + + collection_formats = {} + + path_params = {} + + query_params = [] + if 'page' in params: + query_params.append(('page', params['page'])) # noqa: E501 + if 'limit' in params: + query_params.append(('limit', params['limit'])) # noqa: E501 + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='InlineResponse2009', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_partial_update(self, uuid, data, **kwargs): # noqa: E501 + """Partially update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_partial_update(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def webhooks_partial_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Partially update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_partial_update_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_partial_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_partial_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_partial_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'PATCH', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_read(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_read(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 + return data + + def webhooks_read_with_http_info(self, uuid, **kwargs): # noqa: E501 + """Retrieve a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_read_with_http_info(uuid, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_read" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_read`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'GET', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) + + def webhooks_update(self, uuid, data, **kwargs): # noqa: E501 + """Update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_update(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + kwargs['_return_http_data_only'] = True + if kwargs.get('async'): + return self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + else: + (data) = self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 + return data + + def webhooks_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 + """Update a Webhook # noqa: E501 + + # noqa: E501 + This method makes a synchronous HTTP request by default. To make an + asynchronous HTTP request, please pass async=True + >>> thread = api.webhooks_update_with_http_info(uuid, data, async=True) + >>> result = thread.get() + + :param async bool + :param str uuid: (required) + :param WebhookSubscription data: (required) + :return: WebhookSubscription + If the method is called asynchronously, + returns the request thread. + """ + + all_params = ['uuid', 'data'] # noqa: E501 + all_params.append('async') + all_params.append('_return_http_data_only') + all_params.append('_preload_content') + all_params.append('_request_timeout') + + params = locals() + for key, val in six.iteritems(params['kwargs']): + if key not in all_params: + raise TypeError( + "Got an unexpected keyword argument '%s'" + " to method webhooks_update" % key + ) + params[key] = val + del params['kwargs'] + # verify the required parameter 'uuid' is set + if ('uuid' not in params or + params['uuid'] is None): + raise ValueError("Missing the required parameter `uuid` when calling `webhooks_update`") # noqa: E501 + # verify the required parameter 'data' is set + if ('data' not in params or + params['data'] is None): + raise ValueError("Missing the required parameter `data` when calling `webhooks_update`") # noqa: E501 + + collection_formats = {} + + path_params = {} + if 'uuid' in params: + path_params['uuid'] = params['uuid'] # noqa: E501 + + query_params = [] + + header_params = {} + + form_params = [] + local_var_files = {} + + body_params = None + if 'data' in params: + body_params = params['data'] + # HTTP header `Accept` + header_params['Accept'] = self.api_client.select_header_accept( + ['application/json']) # noqa: E501 + + # HTTP header `Content-Type` + header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 + ['application/json']) # noqa: E501 + + # Authentication setting + auth_settings = ['Token'] # noqa: E501 + + return self.api_client.call_api( + '/webhooks/{uuid}/', 'PUT', + path_params, + query_params, + header_params, + body=body_params, + post_params=form_params, + files=local_var_files, + response_type='WebhookSubscription', # noqa: E501 + auth_settings=auth_settings, + async=params.get('async'), + _return_http_data_only=params.get('_return_http_data_only'), + _preload_content=params.get('_preload_content', True), + _request_timeout=params.get('_request_timeout'), + collection_formats=collection_formats) diff --git a/signrequest_client/api_client.py b/signrequest_client/api_client.py new file mode 100644 index 0000000..57b58d3 --- /dev/null +++ b/signrequest_client/api_client.py @@ -0,0 +1,621 @@ +# coding: utf-8 +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + +from __future__ import absolute_import + +import datetime +import json +import mimetypes +from multiprocessing.pool import ThreadPool +import os +import re +import tempfile + +# python 2 and python 3 compatibility library +import six +from six.moves.urllib.parse import quote + +from signrequest_client.configuration import Configuration +import signrequest_client.models +from signrequest_client import rest + + +class ApiClient(object): + """Generic API client for Swagger client library builds. + + Swagger generic API client. This client handles the client- + server communication, and is invariant across implementations. Specifics of + the methods and models for each application are generated from the Swagger + templates. + + NOTE: This class is auto generated by the swagger code generator program. + Ref: https://github.com/swagger-api/swagger-codegen + Do not edit the class manually. + + :param configuration: .Configuration object for this client + :param header_name: a header to pass when making calls to the API. + :param header_value: a header value to pass when making calls to + the API. + :param cookie: a cookie to include in the header when making calls + to the API + """ + + PRIMITIVE_TYPES = (float, bool, bytes, six.text_type) + six.integer_types + NATIVE_TYPES_MAPPING = { + 'int': int, + 'long': int if six.PY3 else long, # noqa: F821 + 'float': float, + 'str': str, + 'bool': bool, + 'date': datetime.date, + 'datetime': datetime.datetime, + 'object': object, + } + + def __init__(self, configuration=None, header_name=None, header_value=None, + cookie=None): + if configuration is None: + configuration = Configuration() + self.configuration = configuration + + self.pool = ThreadPool() + self.rest_client = rest.RESTClientObject(configuration) + self.default_headers = {} + if header_name is not None: + self.default_headers[header_name] = header_value + self.cookie = cookie + # Set default User-Agent. + self.user_agent = 'Swagger-Codegen/1.0.0/python' + + def __del__(self): + self.pool.close() + self.pool.join() + + @property + def user_agent(self): + """User agent for this API client""" + return self.default_headers['User-Agent'] + + @user_agent.setter + def user_agent(self, value): + self.default_headers['User-Agent'] = value + + def set_default_header(self, header_name, header_value): + self.default_headers[header_name] = header_value + + def __call_api( + self, resource_path, method, path_params=None, + query_params=None, header_params=None, body=None, post_params=None, + files=None, response_type=None, auth_settings=None, + _return_http_data_only=None, collection_formats=None, + _preload_content=True, _request_timeout=None): + + config = self.configuration + + # header parameters + header_params = header_params or {} + header_params.update(self.default_headers) + if self.cookie: + header_params['Cookie'] = self.cookie + if header_params: + header_params = self.sanitize_for_serialization(header_params) + header_params = dict(self.parameters_to_tuples(header_params, + collection_formats)) + + # path parameters + if path_params: + path_params = self.sanitize_for_serialization(path_params) + path_params = self.parameters_to_tuples(path_params, + collection_formats) + for k, v in path_params: + # specified safe chars, encode everything + resource_path = resource_path.replace( + '{%s}' % k, + quote(str(v), safe=config.safe_chars_for_path_param) + ) + + # query parameters + if query_params: + query_params = self.sanitize_for_serialization(query_params) + query_params = self.parameters_to_tuples(query_params, + collection_formats) + + # post parameters + if post_params or files: + post_params = self.prepare_post_parameters(post_params, files) + post_params = self.sanitize_for_serialization(post_params) + post_params = self.parameters_to_tuples(post_params, + collection_formats) + + # auth setting + self.update_params_for_auth(header_params, query_params, auth_settings) + + # body + if body: + body = self.sanitize_for_serialization(body) + + # request url + url = self.configuration.host + resource_path + + # perform request and return response + response_data = self.request( + method, url, query_params=query_params, headers=header_params, + post_params=post_params, body=body, + _preload_content=_preload_content, + _request_timeout=_request_timeout) + + self.last_response = response_data + + return_data = response_data + if _preload_content: + # deserialize response data + if response_type: + return_data = self.deserialize(response_data, response_type) + else: + return_data = None + + if _return_http_data_only: + return (return_data) + else: + return (return_data, response_data.status, + response_data.getheaders()) + + def sanitize_for_serialization(self, obj): + """Builds a JSON POST object. + + If obj is None, return None. + If obj is str, int, long, float, bool, return directly. + If obj is datetime.datetime, datetime.date + convert to string in iso8601 format. + If obj is list, sanitize each element in the list. + If obj is dict, return the dict. + If obj is swagger model, return the properties dict. + + :param obj: The data to serialize. + :return: The serialized form of data. + """ + if obj is None: + return None + elif isinstance(obj, self.PRIMITIVE_TYPES): + return obj + elif isinstance(obj, list): + return [self.sanitize_for_serialization(sub_obj) + for sub_obj in obj] + elif isinstance(obj, tuple): + return tuple(self.sanitize_for_serialization(sub_obj) + for sub_obj in obj) + elif isinstance(obj, (datetime.datetime, datetime.date)): + return obj.isoformat() + + if isinstance(obj, dict): + obj_dict = obj + else: + # Convert model obj to dict except + # attributes `swagger_types`, `attribute_map` + # and attributes which value is not None. + # Convert attribute name to json key in + # model definition for request. + obj_dict = {obj.attribute_map[attr]: getattr(obj, attr) + for attr, _ in six.iteritems(obj.swagger_types) + if getattr(obj, attr) is not None} + + return {key: self.sanitize_for_serialization(val) + for key, val in six.iteritems(obj_dict)} + + def deserialize(self, response, response_type): + """Deserializes response into an object. + + :param response: RESTResponse object to be deserialized. + :param response_type: class literal for + deserialized object, or string of class name. + + :return: deserialized object. + """ + # handle file downloading + # save response body into a tmp file and return the instance + if response_type == "file": + return self.__deserialize_file(response) + + # fetch data from response object + try: + data = json.loads(response.data) + except ValueError: + data = response.data + + return self.__deserialize(data, response_type) + + def __deserialize(self, data, klass): + """Deserializes dict, list, str into an object. + + :param data: dict, list or str. + :param klass: class literal, or string of class name. + + :return: object. + """ + if data is None: + return None + + if type(klass) == str: + if klass.startswith('list['): + sub_kls = re.match('list\[(.*)\]', klass).group(1) + return [self.__deserialize(sub_data, sub_kls) + for sub_data in data] + + if klass.startswith('dict('): + sub_kls = re.match('dict\(([^,]*), (.*)\)', klass).group(2) + return {k: self.__deserialize(v, sub_kls) + for k, v in six.iteritems(data)} + + # convert str to class + if klass in self.NATIVE_TYPES_MAPPING: + klass = self.NATIVE_TYPES_MAPPING[klass] + else: + klass = getattr(signrequest_client.models, klass) + + if klass in self.PRIMITIVE_TYPES: + return self.__deserialize_primitive(data, klass) + elif klass == object: + return self.__deserialize_object(data) + elif klass == datetime.date: + return self.__deserialize_date(data) + elif klass == datetime.datetime: + return self.__deserialize_datatime(data) + else: + return self.__deserialize_model(data, klass) + + def call_api(self, resource_path, method, + path_params=None, query_params=None, header_params=None, + body=None, post_params=None, files=None, + response_type=None, auth_settings=None, async=None, + _return_http_data_only=None, collection_formats=None, + _preload_content=True, _request_timeout=None): + """Makes the HTTP request (synchronous) and returns deserialized data. + + To make an async request, set the async parameter. + + :param resource_path: Path to method endpoint. + :param method: Method to call. + :param path_params: Path parameters in the url. + :param query_params: Query parameters in the url. + :param header_params: Header parameters to be + placed in the request header. + :param body: Request body. + :param post_params dict: Request post form parameters, + for `application/x-www-form-urlencoded`, `multipart/form-data`. + :param auth_settings list: Auth Settings names for the request. + :param response: Response data type. + :param files dict: key -> filename, value -> filepath, + for `multipart/form-data`. + :param async bool: execute request asynchronously + :param _return_http_data_only: response data without head status code + and headers + :param collection_formats: dict of collection formats for path, query, + header, and post parameters. + :param _preload_content: if False, the urllib3.HTTPResponse object will + be returned without reading/decoding response + data. Default is True. + :param _request_timeout: timeout setting for this request. If one + number provided, it will be total request + timeout. It can also be a pair (tuple) of + (connection, read) timeouts. + :return: + If async parameter is True, + the request will be called asynchronously. + The method will return the request thread. + If parameter async is False or missing, + then the method will return the response directly. + """ + if not async: + return self.__call_api(resource_path, method, + path_params, query_params, header_params, + body, post_params, files, + response_type, auth_settings, + _return_http_data_only, collection_formats, + _preload_content, _request_timeout) + else: + thread = self.pool.apply_async(self.__call_api, (resource_path, + method, path_params, query_params, + header_params, body, + post_params, files, + response_type, auth_settings, + _return_http_data_only, + collection_formats, + _preload_content, _request_timeout)) + return thread + + def request(self, method, url, query_params=None, headers=None, + post_params=None, body=None, _preload_content=True, + _request_timeout=None): + """Makes the HTTP request using RESTClient.""" + if method == "GET": + return self.rest_client.GET(url, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + headers=headers) + elif method == "HEAD": + return self.rest_client.HEAD(url, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + headers=headers) + elif method == "OPTIONS": + return self.rest_client.OPTIONS(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "POST": + return self.rest_client.POST(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "PUT": + return self.rest_client.PUT(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "PATCH": + return self.rest_client.PATCH(url, + query_params=query_params, + headers=headers, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + elif method == "DELETE": + return self.rest_client.DELETE(url, + query_params=query_params, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + else: + raise ValueError( + "http method must be `GET`, `HEAD`, `OPTIONS`," + " `POST`, `PATCH`, `PUT` or `DELETE`." + ) + + def parameters_to_tuples(self, params, collection_formats): + """Get parameters as list of tuples, formatting collections. + + :param params: Parameters as dict or list of two-tuples + :param dict collection_formats: Parameter collection formats + :return: Parameters as list of tuples, collections formatted + """ + new_params = [] + if collection_formats is None: + collection_formats = {} + for k, v in six.iteritems(params) if isinstance(params, dict) else params: # noqa: E501 + if k in collection_formats: + collection_format = collection_formats[k] + if collection_format == 'multi': + new_params.extend((k, value) for value in v) + else: + if collection_format == 'ssv': + delimiter = ' ' + elif collection_format == 'tsv': + delimiter = '\t' + elif collection_format == 'pipes': + delimiter = '|' + else: # csv is the default + delimiter = ',' + new_params.append( + (k, delimiter.join(str(value) for value in v))) + else: + new_params.append((k, v)) + return new_params + + def prepare_post_parameters(self, post_params=None, files=None): + """Builds form parameters. + + :param post_params: Normal form parameters. + :param files: File parameters. + :return: Form parameters with files. + """ + params = [] + + if post_params: + params = post_params + + if files: + for k, v in six.iteritems(files): + if not v: + continue + file_names = v if type(v) is list else [v] + for n in file_names: + with open(n, 'rb') as f: + filename = os.path.basename(f.name) + filedata = f.read() + mimetype = (mimetypes.guess_type(filename)[0] or + 'application/octet-stream') + params.append( + tuple([k, tuple([filename, filedata, mimetype])])) + + return params + + def select_header_accept(self, accepts): + """Returns `Accept` based on an array of accepts provided. + + :param accepts: List of headers. + :return: Accept (e.g. application/json). + """ + if not accepts: + return + + accepts = [x.lower() for x in accepts] + + if 'application/json' in accepts: + return 'application/json' + else: + return ', '.join(accepts) + + def select_header_content_type(self, content_types): + """Returns `Content-Type` based on an array of content_types provided. + + :param content_types: List of content-types. + :return: Content-Type (e.g. application/json). + """ + if not content_types: + return 'application/json' + + content_types = [x.lower() for x in content_types] + + if 'application/json' in content_types or '*/*' in content_types: + return 'application/json' + else: + return content_types[0] + + def update_params_for_auth(self, headers, querys, auth_settings): + """Updates header and query params based on authentication setting. + + :param headers: Header parameters dict to be updated. + :param querys: Query parameters tuple list to be updated. + :param auth_settings: Authentication setting identifiers list. + """ + if not auth_settings: + return + + for auth in auth_settings: + auth_setting = self.configuration.auth_settings().get(auth) + if auth_setting: + if not auth_setting['value']: + continue + elif auth_setting['in'] == 'header': + headers[auth_setting['key']] = auth_setting['value'] + elif auth_setting['in'] == 'query': + querys.append((auth_setting['key'], auth_setting['value'])) + else: + raise ValueError( + 'Authentication token must be in `query` or `header`' + ) + + def __deserialize_file(self, response): + """Deserializes body to file + + Saves response body into a file in a temporary folder, + using the filename from the `Content-Disposition` header if provided. + + :param response: RESTResponse. + :return: file path. + """ + fd, path = tempfile.mkstemp(dir=self.configuration.temp_folder_path) + os.close(fd) + os.remove(path) + + content_disposition = response.getheader("Content-Disposition") + if content_disposition: + filename = re.search(r'filename=[\'"]?([^\'"\s]+)[\'"]?', + content_disposition).group(1) + path = os.path.join(os.path.dirname(path), filename) + + with open(path, "wb") as f: + f.write(response.data) + + return path + + def __deserialize_primitive(self, data, klass): + """Deserializes string to primitive type. + + :param data: str. + :param klass: class literal. + + :return: int, long, float, str, bool. + """ + try: + return klass(data) + except UnicodeEncodeError: + return six.u(data) + except TypeError: + return data + + def __deserialize_object(self, value): + """Return a original value. + + :return: object. + """ + return value + + def __deserialize_date(self, string): + """Deserializes string to date. + + :param string: str. + :return: date. + """ + try: + from dateutil.parser import parse + return parse(string).date() + except ImportError: + return string + except ValueError: + raise rest.ApiException( + status=0, + reason="Failed to parse `{0}` as date object".format(string) + ) + + def __deserialize_datatime(self, string): + """Deserializes string to datetime. + + The string should be in iso8601 datetime format. + + :param string: str. + :return: datetime. + """ + try: + from dateutil.parser import parse + return parse(string) + except ImportError: + return string + except ValueError: + raise rest.ApiException( + status=0, + reason=( + "Failed to parse `{0}` as datetime object" + .format(string) + ) + ) + + def __deserialize_model(self, data, klass): + """Deserializes list or dict to model. + + :param data: dict, list. + :param klass: class literal. + :return: model object. + """ + + if not klass.swagger_types and not hasattr(klass, + 'get_real_child_model'): + return data + + kwargs = {} + if klass.swagger_types is not None: + for attr, attr_type in six.iteritems(klass.swagger_types): + if (data is not None and + klass.attribute_map[attr] in data and + isinstance(data, (list, dict))): + value = data[klass.attribute_map[attr]] + kwargs[attr] = self.__deserialize(value, attr_type) + + instance = klass(**kwargs) + + if hasattr(instance, 'get_real_child_model'): + klass_name = instance.get_real_child_model(data) + if klass_name: + instance = self.__deserialize(data, klass_name) + return instance diff --git a/signrequest_client/configuration.py b/signrequest_client/configuration.py new file mode 100644 index 0000000..cb29b7e --- /dev/null +++ b/signrequest_client/configuration.py @@ -0,0 +1,247 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import copy +import logging +import multiprocessing +import sys +import urllib3 + +import six +from six.moves import http_client as httplib + + +class TypeWithDefault(type): + def __init__(cls, name, bases, dct): + super(TypeWithDefault, cls).__init__(name, bases, dct) + cls._default = None + + def __call__(cls): + if cls._default is None: + cls._default = type.__call__(cls) + return copy.copy(cls._default) + + def set_default(cls, default): + cls._default = copy.copy(default) + + +class Configuration(six.with_metaclass(TypeWithDefault, object)): + """NOTE: This class is auto generated by the swagger code generator program. + + Ref: https://github.com/swagger-api/swagger-codegen + Do not edit the class manually. + """ + + def __init__(self): + """Constructor""" + # Default Base url + self.host = "https://signrequest.com/api/v1" + # Temp file folder for downloading files + self.temp_folder_path = None + + # Authentication Settings + # dict to store API key(s) + self.api_key = {} + # dict to store API prefix (e.g. Bearer) + self.api_key_prefix = {} + # Username for HTTP basic authentication + self.username = "" + # Password for HTTP basic authentication + self.password = "" + + # Logging Settings + self.logger = {} + self.logger["package_logger"] = logging.getLogger("signrequest_client") + self.logger["urllib3_logger"] = logging.getLogger("urllib3") + # Log format + self.logger_format = '%(asctime)s %(levelname)s %(message)s' + # Log stream handler + self.logger_stream_handler = None + # Log file handler + self.logger_file_handler = None + # Debug file location + self.logger_file = None + # Debug switch + self.debug = False + + # SSL/TLS verification + # Set this to false to skip verifying SSL certificate when calling API + # from https server. + self.verify_ssl = True + # Set this to customize the certificate file to verify the peer. + self.ssl_ca_cert = None + # client certificate file + self.cert_file = None + # client key file + self.key_file = None + # Set this to True/False to enable/disable SSL hostname verification. + self.assert_hostname = None + + # urllib3 connection pool's maximum number of connections saved + # per pool. urllib3 uses 1 connection as default value, but this is + # not the best value when you are making a lot of possibly parallel + # requests to the same host, which is often the case here. + # cpu_count * 5 is used as default value to increase performance. + self.connection_pool_maxsize = multiprocessing.cpu_count() * 5 + + # Proxy URL + self.proxy = None + # Safe chars for path_param + self.safe_chars_for_path_param = '' + + @property + def logger_file(self): + """The logger file. + + If the logger_file is None, then add stream handler and remove file + handler. Otherwise, add file handler and remove stream handler. + + :param value: The logger_file path. + :type: str + """ + return self.__logger_file + + @logger_file.setter + def logger_file(self, value): + """The logger file. + + If the logger_file is None, then add stream handler and remove file + handler. Otherwise, add file handler and remove stream handler. + + :param value: The logger_file path. + :type: str + """ + self.__logger_file = value + if self.__logger_file: + # If set logging file, + # then add file handler and remove stream handler. + self.logger_file_handler = logging.FileHandler(self.__logger_file) + self.logger_file_handler.setFormatter(self.logger_formatter) + for _, logger in six.iteritems(self.logger): + logger.addHandler(self.logger_file_handler) + if self.logger_stream_handler: + logger.removeHandler(self.logger_stream_handler) + else: + # If not set logging file, + # then add stream handler and remove file handler. + self.logger_stream_handler = logging.StreamHandler() + self.logger_stream_handler.setFormatter(self.logger_formatter) + for _, logger in six.iteritems(self.logger): + logger.addHandler(self.logger_stream_handler) + if self.logger_file_handler: + logger.removeHandler(self.logger_file_handler) + + @property + def debug(self): + """Debug status + + :param value: The debug status, True or False. + :type: bool + """ + return self.__debug + + @debug.setter + def debug(self, value): + """Debug status + + :param value: The debug status, True or False. + :type: bool + """ + self.__debug = value + if self.__debug: + # if debug status is True, turn on debug logging + for _, logger in six.iteritems(self.logger): + logger.setLevel(logging.DEBUG) + # turn on httplib debug + httplib.HTTPConnection.debuglevel = 1 + else: + # if debug status is False, turn off debug logging, + # setting log level to default `logging.WARNING` + for _, logger in six.iteritems(self.logger): + logger.setLevel(logging.WARNING) + # turn off httplib debug + httplib.HTTPConnection.debuglevel = 0 + + @property + def logger_format(self): + """The logger format. + + The logger_formatter will be updated when sets logger_format. + + :param value: The format string. + :type: str + """ + return self.__logger_format + + @logger_format.setter + def logger_format(self, value): + """The logger format. + + The logger_formatter will be updated when sets logger_format. + + :param value: The format string. + :type: str + """ + self.__logger_format = value + self.logger_formatter = logging.Formatter(self.__logger_format) + + def get_api_key_with_prefix(self, identifier): + """Gets API key (with prefix if set). + + :param identifier: The identifier of apiKey. + :return: The token for api key authentication. + """ + if (self.api_key.get(identifier) and + self.api_key_prefix.get(identifier)): + return self.api_key_prefix[identifier] + ' ' + self.api_key[identifier] # noqa: E501 + elif self.api_key.get(identifier): + return self.api_key[identifier] + + def get_basic_auth_token(self): + """Gets HTTP basic authentication header (string). + + :return: The token for basic HTTP authentication. + """ + return urllib3.util.make_headers( + basic_auth=self.username + ':' + self.password + ).get('authorization') + + def auth_settings(self): + """Gets Auth Settings dict for api client. + + :return: The Auth Settings information dict. + """ + return { + 'Token': + { + 'type': 'api_key', + 'in': 'header', + 'key': 'Authorization', + 'value': self.get_api_key_with_prefix('Authorization') + }, + + } + + def to_debug_report(self): + """Gets the essential information for debugging. + + :return: The report for debugging. + """ + return "Python SDK Debug Report:\n"\ + "OS: {env}\n"\ + "Python Version: {pyversion}\n"\ + "Version of the API: v1\n"\ + "SDK Package Version: 1.0.0".\ + format(env=sys.platform, pyversion=sys.version) diff --git a/signrequest_client/models/__init__.py b/signrequest_client/models/__init__.py new file mode 100644 index 0000000..3ee1854 --- /dev/null +++ b/signrequest_client/models/__init__.py @@ -0,0 +1,56 @@ +# coding: utf-8 + +# flake8: noqa +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +# import models into model package +from signrequest_client.models.auth_token import AuthToken +from signrequest_client.models.document import Document +from signrequest_client.models.document_attachment import DocumentAttachment +from signrequest_client.models.document_search import DocumentSearch +from signrequest_client.models.document_signer_template_conf import DocumentSignerTemplateConf +from signrequest_client.models.event import Event +from signrequest_client.models.file_from_sf import FileFromSf +from signrequest_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData +from signrequest_client.models.inline_integration_data import InlineIntegrationData +from signrequest_client.models.inline_prefill_tags import InlinePrefillTags +from signrequest_client.models.inline_response_200 import InlineResponse200 +from signrequest_client.models.inline_response_200_1 import InlineResponse2001 +from signrequest_client.models.inline_response_200_2 import InlineResponse2002 +from signrequest_client.models.inline_response_200_3 import InlineResponse2003 +from signrequest_client.models.inline_response_200_4 import InlineResponse2004 +from signrequest_client.models.inline_response_200_5 import InlineResponse2005 +from signrequest_client.models.inline_response_200_6 import InlineResponse2006 +from signrequest_client.models.inline_response_200_7 import InlineResponse2007 +from signrequest_client.models.inline_response_200_8 import InlineResponse2008 +from signrequest_client.models.inline_response_200_9 import InlineResponse2009 +from signrequest_client.models.inline_response_201 import InlineResponse201 +from signrequest_client.models.inline_response_201_1 import InlineResponse2011 +from signrequest_client.models.inline_sign_request import InlineSignRequest +from signrequest_client.models.inline_team import InlineTeam +from signrequest_client.models.inline_team_member import InlineTeamMember +from signrequest_client.models.invite_member import InviteMember +from signrequest_client.models.placeholder import Placeholder +from signrequest_client.models.required_attachment import RequiredAttachment +from signrequest_client.models.sign_request import SignRequest +from signrequest_client.models.sign_request_quick_create import SignRequestQuickCreate +from signrequest_client.models.signer import Signer +from signrequest_client.models.signer_attachment import SignerAttachment +from signrequest_client.models.signer_inputs import SignerInputs +from signrequest_client.models.signing_log import SigningLog +from signrequest_client.models.team import Team +from signrequest_client.models.team_member import TeamMember +from signrequest_client.models.template import Template +from signrequest_client.models.user import User +from signrequest_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_client/models/auth_token.py b/signrequest_client/models/auth_token.py new file mode 100644 index 0000000..613a34f --- /dev/null +++ b/signrequest_client/models/auth_token.py @@ -0,0 +1,251 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class AuthToken(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'password': 'str', + 'subdomain': 'str', + 'name': 'str', + 'key': 'str', + 'url': 'str' + } + + attribute_map = { + 'email': 'email', + 'password': 'password', + 'subdomain': 'subdomain', + 'name': 'name', + 'key': 'key', + 'url': 'url' + } + + def __init__(self, email=None, password=None, subdomain=None, name=None, key=None, url=None): # noqa: E501 + """AuthToken - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._password = None + self._subdomain = None + self._name = None + self._key = None + self._url = None + self.discriminator = None + + if email is not None: + self.email = email + if password is not None: + self.password = password + self.subdomain = subdomain + if name is not None: + self.name = name + if key is not None: + self.key = key + if url is not None: + self.url = url + + @property + def email(self): + """Gets the email of this AuthToken. # noqa: E501 + + + :return: The email of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this AuthToken. + + + :param email: The email of this AuthToken. # noqa: E501 + :type: str + """ + + self._email = email + + @property + def password(self): + """Gets the password of this AuthToken. # noqa: E501 + + + :return: The password of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._password + + @password.setter + def password(self, password): + """Sets the password of this AuthToken. + + + :param password: The password of this AuthToken. # noqa: E501 + :type: str + """ + + self._password = password + + @property + def subdomain(self): + """Gets the subdomain of this AuthToken. # noqa: E501 + + + :return: The subdomain of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this AuthToken. + + + :param subdomain: The subdomain of this AuthToken. # noqa: E501 + :type: str + """ + if subdomain is None: + raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 + raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 + + self._subdomain = subdomain + + @property + def name(self): + """Gets the name of this AuthToken. # noqa: E501 + + + :return: The name of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this AuthToken. + + + :param name: The name of this AuthToken. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def key(self): + """Gets the key of this AuthToken. # noqa: E501 + + + :return: The key of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._key + + @key.setter + def key(self, key): + """Sets the key of this AuthToken. + + + :param key: The key of this AuthToken. # noqa: E501 + :type: str + """ + if key is not None and len(key) < 1: + raise ValueError("Invalid value for `key`, length must be greater than or equal to `1`") # noqa: E501 + + self._key = key + + @property + def url(self): + """Gets the url of this AuthToken. # noqa: E501 + + + :return: The url of this AuthToken. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this AuthToken. + + + :param url: The url of this AuthToken. # noqa: E501 + :type: str + """ + + self._url = url + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, AuthToken): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/document.py b/signrequest_client/models/document.py new file mode 100644 index 0000000..6a8a0fa --- /dev/null +++ b/signrequest_client/models/document.py @@ -0,0 +1,748 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 +from signrequest_client.models.file_from_sf import FileFromSf # noqa: F401,E501 +from signrequest_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 +from signrequest_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 +from signrequest_client.models.user import User # noqa: F401,E501 + + +class Document(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'user': 'User', + 'file_as_pdf': 'str', + 'name': 'str', + 'external_id': 'str', + 'frontend_id': 'str', + 'file': 'str', + 'file_from_url': 'str', + 'events_callback_url': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'template': 'str', + 'prefill_tags': 'list[InlinePrefillTags]', + 'integrations': 'list[InlineIntegrationData]', + 'file_from_sf': 'FileFromSf', + 'auto_delete_days': 'int', + 'pdf': 'str', + 'status': 'str', + 'api_used': 'bool', + 'security_hash': 'str', + 'attachments': 'list[DocumentAttachment]', + 'auto_delete_after': 'datetime' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'user': 'user', + 'file_as_pdf': 'file_as_pdf', + 'name': 'name', + 'external_id': 'external_id', + 'frontend_id': 'frontend_id', + 'file': 'file', + 'file_from_url': 'file_from_url', + 'events_callback_url': 'events_callback_url', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'template': 'template', + 'prefill_tags': 'prefill_tags', + 'integrations': 'integrations', + 'file_from_sf': 'file_from_sf', + 'auto_delete_days': 'auto_delete_days', + 'pdf': 'pdf', + 'status': 'status', + 'api_used': 'api_used', + 'security_hash': 'security_hash', + 'attachments': 'attachments', + 'auto_delete_after': 'auto_delete_after' + } + + def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None, pdf=None, status=None, api_used=None, security_hash=None, attachments=None, auto_delete_after=None): # noqa: E501 + """Document - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._user = None + self._file_as_pdf = None + self._name = None + self._external_id = None + self._frontend_id = None + self._file = None + self._file_from_url = None + self._events_callback_url = None + self._file_from_content = None + self._file_from_content_name = None + self._template = None + self._prefill_tags = None + self._integrations = None + self._file_from_sf = None + self._auto_delete_days = None + self._pdf = None + self._status = None + self._api_used = None + self._security_hash = None + self._attachments = None + self._auto_delete_after = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if user is not None: + self.user = user + if file_as_pdf is not None: + self.file_as_pdf = file_as_pdf + if name is not None: + self.name = name + if external_id is not None: + self.external_id = external_id + if frontend_id is not None: + self.frontend_id = frontend_id + if file is not None: + self.file = file + if file_from_url is not None: + self.file_from_url = file_from_url + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if template is not None: + self.template = template + if prefill_tags is not None: + self.prefill_tags = prefill_tags + if integrations is not None: + self.integrations = integrations + if file_from_sf is not None: + self.file_from_sf = file_from_sf + if auto_delete_days is not None: + self.auto_delete_days = auto_delete_days + if pdf is not None: + self.pdf = pdf + if status is not None: + self.status = status + if api_used is not None: + self.api_used = api_used + if security_hash is not None: + self.security_hash = security_hash + if attachments is not None: + self.attachments = attachments + if auto_delete_after is not None: + self.auto_delete_after = auto_delete_after + + @property + def url(self): + """Gets the url of this Document. # noqa: E501 + + + :return: The url of this Document. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Document. + + + :param url: The url of this Document. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this Document. # noqa: E501 + + + :return: The uuid of this Document. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Document. + + + :param uuid: The uuid of this Document. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def user(self): + """Gets the user of this Document. # noqa: E501 + + + :return: The user of this Document. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this Document. + + + :param user: The user of this Document. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def file_as_pdf(self): + """Gets the file_as_pdf of this Document. # noqa: E501 + + Temporary URL to original file as PDF, expires in five minutes # noqa: E501 + + :return: The file_as_pdf of this Document. # noqa: E501 + :rtype: str + """ + return self._file_as_pdf + + @file_as_pdf.setter + def file_as_pdf(self, file_as_pdf): + """Sets the file_as_pdf of this Document. + + Temporary URL to original file as PDF, expires in five minutes # noqa: E501 + + :param file_as_pdf: The file_as_pdf of this Document. # noqa: E501 + :type: str + """ + if file_as_pdf is not None and len(file_as_pdf) < 1: + raise ValueError("Invalid value for `file_as_pdf`, length must be greater than or equal to `1`") # noqa: E501 + + self._file_as_pdf = file_as_pdf + + @property + def name(self): + """Gets the name of this Document. # noqa: E501 + + Defaults to filename, including extension # noqa: E501 + + :return: The name of this Document. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Document. + + Defaults to filename, including extension # noqa: E501 + + :param name: The name of this Document. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def external_id(self): + """Gets the external_id of this Document. # noqa: E501 + + ID used to reference document in external system # noqa: E501 + + :return: The external_id of this Document. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this Document. + + ID used to reference document in external system # noqa: E501 + + :param external_id: The external_id of this Document. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def frontend_id(self): + """Gets the frontend_id of this Document. # noqa: E501 + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :return: The frontend_id of this Document. # noqa: E501 + :rtype: str + """ + return self._frontend_id + + @frontend_id.setter + def frontend_id(self, frontend_id): + """Sets the frontend_id of this Document. + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :param frontend_id: The frontend_id of this Document. # noqa: E501 + :type: str + """ + if frontend_id is not None and len(frontend_id) > 255: + raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 + + self._frontend_id = frontend_id + + @property + def file(self): + """Gets the file of this Document. # noqa: E501 + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :return: The file of this Document. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this Document. + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :param file: The file of this Document. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_url(self): + """Gets the file_from_url of this Document. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this Document. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this Document. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def events_callback_url(self): + """Gets the events_callback_url of this Document. # noqa: E501 + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :return: The events_callback_url of this Document. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this Document. + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :param events_callback_url: The events_callback_url of this Document. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def file_from_content(self): + """Gets the file_from_content of this Document. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this Document. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this Document. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this Document. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this Document. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this Document. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this Document. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def template(self): + """Gets the template of this Document. # noqa: E501 + + + :return: The template of this Document. # noqa: E501 + :rtype: str + """ + return self._template + + @template.setter + def template(self, template): + """Sets the template of this Document. + + + :param template: The template of this Document. # noqa: E501 + :type: str + """ + + self._template = template + + @property + def prefill_tags(self): + """Gets the prefill_tags of this Document. # noqa: E501 + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :return: The prefill_tags of this Document. # noqa: E501 + :rtype: list[InlinePrefillTags] + """ + return self._prefill_tags + + @prefill_tags.setter + def prefill_tags(self, prefill_tags): + """Sets the prefill_tags of this Document. + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :param prefill_tags: The prefill_tags of this Document. # noqa: E501 + :type: list[InlinePrefillTags] + """ + + self._prefill_tags = prefill_tags + + @property + def integrations(self): + """Gets the integrations of this Document. # noqa: E501 + + + :return: The integrations of this Document. # noqa: E501 + :rtype: list[InlineIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this Document. + + + :param integrations: The integrations of this Document. # noqa: E501 + :type: list[InlineIntegrationData] + """ + + self._integrations = integrations + + @property + def file_from_sf(self): + """Gets the file_from_sf of this Document. # noqa: E501 + + + :return: The file_from_sf of this Document. # noqa: E501 + :rtype: FileFromSf + """ + return self._file_from_sf + + @file_from_sf.setter + def file_from_sf(self, file_from_sf): + """Sets the file_from_sf of this Document. + + + :param file_from_sf: The file_from_sf of this Document. # noqa: E501 + :type: FileFromSf + """ + + self._file_from_sf = file_from_sf + + @property + def auto_delete_days(self): + """Gets the auto_delete_days of this Document. # noqa: E501 + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_days of this Document. # noqa: E501 + :rtype: int + """ + return self._auto_delete_days + + @auto_delete_days.setter + def auto_delete_days(self, auto_delete_days): + """Sets the auto_delete_days of this Document. + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_days: The auto_delete_days of this Document. # noqa: E501 + :type: int + """ + if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 + if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 + + self._auto_delete_days = auto_delete_days + + @property + def pdf(self): + """Gets the pdf of this Document. # noqa: E501 + + Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 + + :return: The pdf of this Document. # noqa: E501 + :rtype: str + """ + return self._pdf + + @pdf.setter + def pdf(self, pdf): + """Sets the pdf of this Document. + + Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 + + :param pdf: The pdf of this Document. # noqa: E501 + :type: str + """ + + self._pdf = pdf + + @property + def status(self): + """Gets the status of this Document. # noqa: E501 + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 + + :return: The status of this Document. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this Document. + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 + + :param status: The status of this Document. # noqa: E501 + :type: str + """ + allowed_values = ["co", "ne", "se", "vi", "si", "do", "sd", "ca", "de", "ec", "es", "xp"] # noqa: E501 + if status not in allowed_values: + raise ValueError( + "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 + .format(status, allowed_values) + ) + + self._status = status + + @property + def api_used(self): + """Gets the api_used of this Document. # noqa: E501 + + Indicates whether document was created using the API # noqa: E501 + + :return: The api_used of this Document. # noqa: E501 + :rtype: bool + """ + return self._api_used + + @api_used.setter + def api_used(self, api_used): + """Sets the api_used of this Document. + + Indicates whether document was created using the API # noqa: E501 + + :param api_used: The api_used of this Document. # noqa: E501 + :type: bool + """ + + self._api_used = api_used + + @property + def security_hash(self): + """Gets the security_hash of this Document. # noqa: E501 + + SHA256 hash of PDF contents # noqa: E501 + + :return: The security_hash of this Document. # noqa: E501 + :rtype: str + """ + return self._security_hash + + @security_hash.setter + def security_hash(self, security_hash): + """Sets the security_hash of this Document. + + SHA256 hash of PDF contents # noqa: E501 + + :param security_hash: The security_hash of this Document. # noqa: E501 + :type: str + """ + if security_hash is not None and len(security_hash) < 1: + raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 + + self._security_hash = security_hash + + @property + def attachments(self): + """Gets the attachments of this Document. # noqa: E501 + + + :return: The attachments of this Document. # noqa: E501 + :rtype: list[DocumentAttachment] + """ + return self._attachments + + @attachments.setter + def attachments(self, attachments): + """Sets the attachments of this Document. + + + :param attachments: The attachments of this Document. # noqa: E501 + :type: list[DocumentAttachment] + """ + + self._attachments = attachments + + @property + def auto_delete_after(self): + """Gets the auto_delete_after of this Document. # noqa: E501 + + Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_after of this Document. # noqa: E501 + :rtype: datetime + """ + return self._auto_delete_after + + @auto_delete_after.setter + def auto_delete_after(self, auto_delete_after): + """Sets the auto_delete_after of this Document. + + Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_after: The auto_delete_after of this Document. # noqa: E501 + :type: datetime + """ + + self._auto_delete_after = auto_delete_after + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Document): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/document_attachment.py b/signrequest_client/models/document_attachment.py new file mode 100644 index 0000000..460af9c --- /dev/null +++ b/signrequest_client/models/document_attachment.py @@ -0,0 +1,311 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class DocumentAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'name': 'str', + 'file': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'file_from_url': 'str', + 'document': 'str' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'name': 'name', + 'file': 'file', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'file_from_url': 'file_from_url', + 'document': 'document' + } + + def __init__(self, url=None, uuid=None, name=None, file=None, file_from_content=None, file_from_content_name=None, file_from_url=None, document=None): # noqa: E501 + """DocumentAttachment - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._name = None + self._file = None + self._file_from_content = None + self._file_from_content_name = None + self._file_from_url = None + self._document = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + if file is not None: + self.file = file + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if file_from_url is not None: + self.file_from_url = file_from_url + self.document = document + + @property + def url(self): + """Gets the url of this DocumentAttachment. # noqa: E501 + + + :return: The url of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this DocumentAttachment. + + + :param url: The url of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this DocumentAttachment. # noqa: E501 + + + :return: The uuid of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this DocumentAttachment. + + + :param uuid: The uuid of this DocumentAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this DocumentAttachment. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this DocumentAttachment. + + Defaults to filename # noqa: E501 + + :param name: The name of this DocumentAttachment. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def file(self): + """Gets the file of this DocumentAttachment. # noqa: E501 + + Temporary URL to document attachment, expires in five minutes # noqa: E501 + + :return: The file of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this DocumentAttachment. + + Temporary URL to document attachment, expires in five minutes # noqa: E501 + + :param file: The file of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_content(self): + """Gets the file_from_content of this DocumentAttachment. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this DocumentAttachment. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this DocumentAttachment. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this DocumentAttachment. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this DocumentAttachment. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def file_from_url(self): + """Gets the file_from_url of this DocumentAttachment. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this DocumentAttachment. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this DocumentAttachment. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def document(self): + """Gets the document of this DocumentAttachment. # noqa: E501 + + + :return: The document of this DocumentAttachment. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this DocumentAttachment. + + + :param document: The document of this DocumentAttachment. # noqa: E501 + :type: str + """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 + + self._document = document + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/document_search.py b/signrequest_client/models/document_search.py new file mode 100644 index 0000000..627bede --- /dev/null +++ b/signrequest_client/models/document_search.py @@ -0,0 +1,504 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class DocumentSearch(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'status': 'str', + 'name': 'str', + 'who': 'str', + 'nr_extra_docs': 'int', + 'from_email': 'str', + 'uuid': 'str', + 'created': 'datetime', + 'autocomplete': 'str', + 'signer_emails': 'list[str]', + 'status_display': 'str', + 'created_timestamp': 'int', + 'finished_on_timestamp': 'int', + 'parent_doc': 'str', + 'finished_on': 'datetime', + 'subdomain': 'str' + } + + attribute_map = { + 'status': 'status', + 'name': 'name', + 'who': 'who', + 'nr_extra_docs': 'nr_extra_docs', + 'from_email': 'from_email', + 'uuid': 'uuid', + 'created': 'created', + 'autocomplete': 'autocomplete', + 'signer_emails': 'signer_emails', + 'status_display': 'status_display', + 'created_timestamp': 'created_timestamp', + 'finished_on_timestamp': 'finished_on_timestamp', + 'parent_doc': 'parent_doc', + 'finished_on': 'finished_on', + 'subdomain': 'subdomain' + } + + def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None, finished_on=None, subdomain=None): # noqa: E501 + """DocumentSearch - a model defined in Swagger""" # noqa: E501 + + self._status = None + self._name = None + self._who = None + self._nr_extra_docs = None + self._from_email = None + self._uuid = None + self._created = None + self._autocomplete = None + self._signer_emails = None + self._status_display = None + self._created_timestamp = None + self._finished_on_timestamp = None + self._parent_doc = None + self._finished_on = None + self._subdomain = None + self.discriminator = None + + if status is not None: + self.status = status + if name is not None: + self.name = name + self.who = who + self.nr_extra_docs = nr_extra_docs + self.from_email = from_email + if uuid is not None: + self.uuid = uuid + if created is not None: + self.created = created + self.autocomplete = autocomplete + if signer_emails is not None: + self.signer_emails = signer_emails + if status_display is not None: + self.status_display = status_display + if created_timestamp is not None: + self.created_timestamp = created_timestamp + if finished_on_timestamp is not None: + self.finished_on_timestamp = finished_on_timestamp + if parent_doc is not None: + self.parent_doc = parent_doc + if finished_on is not None: + self.finished_on = finished_on + if subdomain is not None: + self.subdomain = subdomain + + @property + def status(self): + """Gets the status of this DocumentSearch. # noqa: E501 + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 + + :return: The status of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this DocumentSearch. + + `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 + + :param status: The status of this DocumentSearch. # noqa: E501 + :type: str + """ + if status is not None and len(status) > 2: + raise ValueError("Invalid value for `status`, length must be less than or equal to `2`") # noqa: E501 + if status is not None and len(status) < 1: + raise ValueError("Invalid value for `status`, length must be greater than or equal to `1`") # noqa: E501 + + self._status = status + + @property + def name(self): + """Gets the name of this DocumentSearch. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this DocumentSearch. + + Defaults to filename # noqa: E501 + + :param name: The name of this DocumentSearch. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def who(self): + """Gets the who of this DocumentSearch. # noqa: E501 + + + :return: The who of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this DocumentSearch. + + + :param who: The who of this DocumentSearch. # noqa: E501 + :type: str + """ + if who is None: + raise ValueError("Invalid value for `who`, must not be `None`") # noqa: E501 + if who is not None and len(who) < 1: + raise ValueError("Invalid value for `who`, length must be greater than or equal to `1`") # noqa: E501 + + self._who = who + + @property + def nr_extra_docs(self): + """Gets the nr_extra_docs of this DocumentSearch. # noqa: E501 + + + :return: The nr_extra_docs of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._nr_extra_docs + + @nr_extra_docs.setter + def nr_extra_docs(self, nr_extra_docs): + """Sets the nr_extra_docs of this DocumentSearch. + + + :param nr_extra_docs: The nr_extra_docs of this DocumentSearch. # noqa: E501 + :type: int + """ + if nr_extra_docs is None: + raise ValueError("Invalid value for `nr_extra_docs`, must not be `None`") # noqa: E501 + + self._nr_extra_docs = nr_extra_docs + + @property + def from_email(self): + """Gets the from_email of this DocumentSearch. # noqa: E501 + + + :return: The from_email of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this DocumentSearch. + + + :param from_email: The from_email of this DocumentSearch. # noqa: E501 + :type: str + """ + if from_email is None: + raise ValueError("Invalid value for `from_email`, must not be `None`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def uuid(self): + """Gets the uuid of this DocumentSearch. # noqa: E501 + + + :return: The uuid of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this DocumentSearch. + + + :param uuid: The uuid of this DocumentSearch. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def created(self): + """Gets the created of this DocumentSearch. # noqa: E501 + + + :return: The created of this DocumentSearch. # noqa: E501 + :rtype: datetime + """ + return self._created + + @created.setter + def created(self, created): + """Sets the created of this DocumentSearch. + + + :param created: The created of this DocumentSearch. # noqa: E501 + :type: datetime + """ + + self._created = created + + @property + def autocomplete(self): + """Gets the autocomplete of this DocumentSearch. # noqa: E501 + + + :return: The autocomplete of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._autocomplete + + @autocomplete.setter + def autocomplete(self, autocomplete): + """Sets the autocomplete of this DocumentSearch. + + + :param autocomplete: The autocomplete of this DocumentSearch. # noqa: E501 + :type: str + """ + if autocomplete is None: + raise ValueError("Invalid value for `autocomplete`, must not be `None`") # noqa: E501 + if autocomplete is not None and len(autocomplete) < 1: + raise ValueError("Invalid value for `autocomplete`, length must be greater than or equal to `1`") # noqa: E501 + + self._autocomplete = autocomplete + + @property + def signer_emails(self): + """Gets the signer_emails of this DocumentSearch. # noqa: E501 + + + :return: The signer_emails of this DocumentSearch. # noqa: E501 + :rtype: list[str] + """ + return self._signer_emails + + @signer_emails.setter + def signer_emails(self, signer_emails): + """Sets the signer_emails of this DocumentSearch. + + + :param signer_emails: The signer_emails of this DocumentSearch. # noqa: E501 + :type: list[str] + """ + + self._signer_emails = signer_emails + + @property + def status_display(self): + """Gets the status_display of this DocumentSearch. # noqa: E501 + + + :return: The status_display of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._status_display + + @status_display.setter + def status_display(self, status_display): + """Sets the status_display of this DocumentSearch. + + + :param status_display: The status_display of this DocumentSearch. # noqa: E501 + :type: str + """ + if status_display is not None and len(status_display) < 1: + raise ValueError("Invalid value for `status_display`, length must be greater than or equal to `1`") # noqa: E501 + + self._status_display = status_display + + @property + def created_timestamp(self): + """Gets the created_timestamp of this DocumentSearch. # noqa: E501 + + + :return: The created_timestamp of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._created_timestamp + + @created_timestamp.setter + def created_timestamp(self, created_timestamp): + """Sets the created_timestamp of this DocumentSearch. + + + :param created_timestamp: The created_timestamp of this DocumentSearch. # noqa: E501 + :type: int + """ + + self._created_timestamp = created_timestamp + + @property + def finished_on_timestamp(self): + """Gets the finished_on_timestamp of this DocumentSearch. # noqa: E501 + + + :return: The finished_on_timestamp of this DocumentSearch. # noqa: E501 + :rtype: int + """ + return self._finished_on_timestamp + + @finished_on_timestamp.setter + def finished_on_timestamp(self, finished_on_timestamp): + """Sets the finished_on_timestamp of this DocumentSearch. + + + :param finished_on_timestamp: The finished_on_timestamp of this DocumentSearch. # noqa: E501 + :type: int + """ + + self._finished_on_timestamp = finished_on_timestamp + + @property + def parent_doc(self): + """Gets the parent_doc of this DocumentSearch. # noqa: E501 + + + :return: The parent_doc of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._parent_doc + + @parent_doc.setter + def parent_doc(self, parent_doc): + """Sets the parent_doc of this DocumentSearch. + + + :param parent_doc: The parent_doc of this DocumentSearch. # noqa: E501 + :type: str + """ + if parent_doc is not None and len(parent_doc) < 1: + raise ValueError("Invalid value for `parent_doc`, length must be greater than or equal to `1`") # noqa: E501 + + self._parent_doc = parent_doc + + @property + def finished_on(self): + """Gets the finished_on of this DocumentSearch. # noqa: E501 + + + :return: The finished_on of this DocumentSearch. # noqa: E501 + :rtype: datetime + """ + return self._finished_on + + @finished_on.setter + def finished_on(self, finished_on): + """Sets the finished_on of this DocumentSearch. + + + :param finished_on: The finished_on of this DocumentSearch. # noqa: E501 + :type: datetime + """ + + self._finished_on = finished_on + + @property + def subdomain(self): + """Gets the subdomain of this DocumentSearch. # noqa: E501 + + + :return: The subdomain of this DocumentSearch. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this DocumentSearch. + + + :param subdomain: The subdomain of this DocumentSearch. # noqa: E501 + :type: str + """ + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + + self._subdomain = subdomain + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentSearch): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/document_signer_template_conf.py b/signrequest_client/models/document_signer_template_conf.py new file mode 100644 index 0000000..978f75e --- /dev/null +++ b/signrequest_client/models/document_signer_template_conf.py @@ -0,0 +1,278 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.placeholder import Placeholder # noqa: F401,E501 + + +class DocumentSignerTemplateConf(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'signer_index': 'int', + 'needs_to_sign': 'bool', + 'approve_only': 'bool', + 'notify_only': 'bool', + 'in_person': 'bool', + 'order': 'int', + 'placeholders': 'list[Placeholder]' + } + + attribute_map = { + 'signer_index': 'signer_index', + 'needs_to_sign': 'needs_to_sign', + 'approve_only': 'approve_only', + 'notify_only': 'notify_only', + 'in_person': 'in_person', + 'order': 'order', + 'placeholders': 'placeholders' + } + + def __init__(self, signer_index=None, needs_to_sign=None, approve_only=None, notify_only=None, in_person=None, order=None, placeholders=None): # noqa: E501 + """DocumentSignerTemplateConf - a model defined in Swagger""" # noqa: E501 + + self._signer_index = None + self._needs_to_sign = None + self._approve_only = None + self._notify_only = None + self._in_person = None + self._order = None + self._placeholders = None + self.discriminator = None + + if signer_index is not None: + self.signer_index = signer_index + if needs_to_sign is not None: + self.needs_to_sign = needs_to_sign + if approve_only is not None: + self.approve_only = approve_only + if notify_only is not None: + self.notify_only = notify_only + if in_person is not None: + self.in_person = in_person + if order is not None: + self.order = order + if placeholders is not None: + self.placeholders = placeholders + + @property + def signer_index(self): + """Gets the signer_index of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: int + """ + return self._signer_index + + @signer_index.setter + def signer_index(self, signer_index): + """Sets the signer_index of this DocumentSignerTemplateConf. + + + :param signer_index: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 + :type: int + """ + if signer_index is not None and signer_index > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `signer_index`, must be a value less than or equal to `2147483647`") # noqa: E501 + if signer_index is not None and signer_index < -2147483648: # noqa: E501 + raise ValueError("Invalid value for `signer_index`, must be a value greater than or equal to `-2147483648`") # noqa: E501 + + self._signer_index = signer_index + + @property + def needs_to_sign(self): + """Gets the needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._needs_to_sign + + @needs_to_sign.setter + def needs_to_sign(self, needs_to_sign): + """Sets the needs_to_sign of this DocumentSignerTemplateConf. + + + :param needs_to_sign: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._needs_to_sign = needs_to_sign + + @property + def approve_only(self): + """Gets the approve_only of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._approve_only + + @approve_only.setter + def approve_only(self, approve_only): + """Sets the approve_only of this DocumentSignerTemplateConf. + + + :param approve_only: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._approve_only = approve_only + + @property + def notify_only(self): + """Gets the notify_only of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._notify_only + + @notify_only.setter + def notify_only(self, notify_only): + """Sets the notify_only of this DocumentSignerTemplateConf. + + + :param notify_only: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._notify_only = notify_only + + @property + def in_person(self): + """Gets the in_person of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The in_person of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: bool + """ + return self._in_person + + @in_person.setter + def in_person(self, in_person): + """Sets the in_person of this DocumentSignerTemplateConf. + + + :param in_person: The in_person of this DocumentSignerTemplateConf. # noqa: E501 + :type: bool + """ + + self._in_person = in_person + + @property + def order(self): + """Gets the order of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The order of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: int + """ + return self._order + + @order.setter + def order(self, order): + """Sets the order of this DocumentSignerTemplateConf. + + + :param order: The order of this DocumentSignerTemplateConf. # noqa: E501 + :type: int + """ + if order is not None and order > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 + if order is not None and order < 0: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 + + self._order = order + + @property + def placeholders(self): + """Gets the placeholders of this DocumentSignerTemplateConf. # noqa: E501 + + + :return: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 + :rtype: list[Placeholder] + """ + return self._placeholders + + @placeholders.setter + def placeholders(self, placeholders): + """Sets the placeholders of this DocumentSignerTemplateConf. + + + :param placeholders: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 + :type: list[Placeholder] + """ + + self._placeholders = placeholders + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, DocumentSignerTemplateConf): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/event.py b/signrequest_client/models/event.py new file mode 100644 index 0000000..8bea01b --- /dev/null +++ b/signrequest_client/models/event.py @@ -0,0 +1,337 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document import Document # noqa: F401,E501 +from signrequest_client.models.signer import Signer # noqa: F401,E501 + + +class Event(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'status': 'str', + 'event_type': 'str', + 'delivered': 'bool', + 'delivered_on': 'datetime', + 'callback_status_code': 'int', + 'timestamp': 'datetime', + 'document': 'Document', + 'signer': 'Signer' + } + + attribute_map = { + 'uuid': 'uuid', + 'status': 'status', + 'event_type': 'event_type', + 'delivered': 'delivered', + 'delivered_on': 'delivered_on', + 'callback_status_code': 'callback_status_code', + 'timestamp': 'timestamp', + 'document': 'document', + 'signer': 'signer' + } + + def __init__(self, uuid=None, status=None, event_type=None, delivered=None, delivered_on=None, callback_status_code=None, timestamp=None, document=None, signer=None): # noqa: E501 + """Event - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._status = None + self._event_type = None + self._delivered = None + self._delivered_on = None + self._callback_status_code = None + self._timestamp = None + self._document = None + self._signer = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if status is not None: + self.status = status + if event_type is not None: + self.event_type = event_type + if delivered is not None: + self.delivered = delivered + if delivered_on is not None: + self.delivered_on = delivered_on + if callback_status_code is not None: + self.callback_status_code = callback_status_code + if timestamp is not None: + self.timestamp = timestamp + if document is not None: + self.document = document + if signer is not None: + self.signer = signer + + @property + def uuid(self): + """Gets the uuid of this Event. # noqa: E501 + + + :return: The uuid of this Event. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Event. + + + :param uuid: The uuid of this Event. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def status(self): + """Gets the status of this Event. # noqa: E501 + + + :return: The status of this Event. # noqa: E501 + :rtype: str + """ + return self._status + + @status.setter + def status(self, status): + """Sets the status of this Event. + + + :param status: The status of this Event. # noqa: E501 + :type: str + """ + allowed_values = ["ok", "error"] # noqa: E501 + if status not in allowed_values: + raise ValueError( + "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 + .format(status, allowed_values) + ) + + self._status = status + + @property + def event_type(self): + """Gets the event_type of this Event. # noqa: E501 + + + :return: The event_type of this Event. # noqa: E501 + :rtype: str + """ + return self._event_type + + @event_type.setter + def event_type(self, event_type): + """Sets the event_type of this Event. + + + :param event_type: The event_type of this Event. # noqa: E501 + :type: str + """ + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + if event_type not in allowed_values: + raise ValueError( + "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 + .format(event_type, allowed_values) + ) + + self._event_type = event_type + + @property + def delivered(self): + """Gets the delivered of this Event. # noqa: E501 + + + :return: The delivered of this Event. # noqa: E501 + :rtype: bool + """ + return self._delivered + + @delivered.setter + def delivered(self, delivered): + """Sets the delivered of this Event. + + + :param delivered: The delivered of this Event. # noqa: E501 + :type: bool + """ + + self._delivered = delivered + + @property + def delivered_on(self): + """Gets the delivered_on of this Event. # noqa: E501 + + + :return: The delivered_on of this Event. # noqa: E501 + :rtype: datetime + """ + return self._delivered_on + + @delivered_on.setter + def delivered_on(self, delivered_on): + """Sets the delivered_on of this Event. + + + :param delivered_on: The delivered_on of this Event. # noqa: E501 + :type: datetime + """ + + self._delivered_on = delivered_on + + @property + def callback_status_code(self): + """Gets the callback_status_code of this Event. # noqa: E501 + + + :return: The callback_status_code of this Event. # noqa: E501 + :rtype: int + """ + return self._callback_status_code + + @callback_status_code.setter + def callback_status_code(self, callback_status_code): + """Sets the callback_status_code of this Event. + + + :param callback_status_code: The callback_status_code of this Event. # noqa: E501 + :type: int + """ + + self._callback_status_code = callback_status_code + + @property + def timestamp(self): + """Gets the timestamp of this Event. # noqa: E501 + + + :return: The timestamp of this Event. # noqa: E501 + :rtype: datetime + """ + return self._timestamp + + @timestamp.setter + def timestamp(self, timestamp): + """Sets the timestamp of this Event. + + + :param timestamp: The timestamp of this Event. # noqa: E501 + :type: datetime + """ + + self._timestamp = timestamp + + @property + def document(self): + """Gets the document of this Event. # noqa: E501 + + + :return: The document of this Event. # noqa: E501 + :rtype: Document + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this Event. + + + :param document: The document of this Event. # noqa: E501 + :type: Document + """ + + self._document = document + + @property + def signer(self): + """Gets the signer of this Event. # noqa: E501 + + + :return: The signer of this Event. # noqa: E501 + :rtype: Signer + """ + return self._signer + + @signer.setter + def signer(self, signer): + """Sets the signer of this Event. + + + :param signer: The signer of this Event. # noqa: E501 + :type: Signer + """ + + self._signer = signer + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Event): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/file_from_sf.py b/signrequest_client/models/file_from_sf.py new file mode 100644 index 0000000..7c90998 --- /dev/null +++ b/signrequest_client/models/file_from_sf.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class FileFromSf(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'object_type': 'str', + 'object_id': 'str' + } + + attribute_map = { + 'object_type': 'object_type', + 'object_id': 'object_id' + } + + def __init__(self, object_type=None, object_id=None): # noqa: E501 + """FileFromSf - a model defined in Swagger""" # noqa: E501 + + self._object_type = None + self._object_id = None + self.discriminator = None + + self.object_type = object_type + self.object_id = object_id + + @property + def object_type(self): + """Gets the object_type of this FileFromSf. # noqa: E501 + + + :return: The object_type of this FileFromSf. # noqa: E501 + :rtype: str + """ + return self._object_type + + @object_type.setter + def object_type(self, object_type): + """Sets the object_type of this FileFromSf. + + + :param object_type: The object_type of this FileFromSf. # noqa: E501 + :type: str + """ + if object_type is None: + raise ValueError("Invalid value for `object_type`, must not be `None`") # noqa: E501 + if object_type is not None and len(object_type) < 1: + raise ValueError("Invalid value for `object_type`, length must be greater than or equal to `1`") # noqa: E501 + + self._object_type = object_type + + @property + def object_id(self): + """Gets the object_id of this FileFromSf. # noqa: E501 + + + :return: The object_id of this FileFromSf. # noqa: E501 + :rtype: str + """ + return self._object_id + + @object_id.setter + def object_id(self, object_id): + """Sets the object_id of this FileFromSf. + + + :param object_id: The object_id of this FileFromSf. # noqa: E501 + :type: str + """ + if object_id is None: + raise ValueError("Invalid value for `object_id`, must not be `None`") # noqa: E501 + if object_id is not None and len(object_id) < 1: + raise ValueError("Invalid value for `object_id`, length must be greater than or equal to `1`") # noqa: E501 + + self._object_id = object_id + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, FileFromSf): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_document_signer_integration_data.py b/signrequest_client/models/inline_document_signer_integration_data.py new file mode 100644 index 0000000..15eeaae --- /dev/null +++ b/signrequest_client/models/inline_document_signer_integration_data.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineDocumentSignerIntegrationData(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, integration=None, integration_data=None): # noqa: E501 + """InlineDocumentSignerIntegrationData - a model defined in Swagger""" # noqa: E501 + + self._integration = None + self._integration_data = None + self.discriminator = None + + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def integration(self): + """Gets the integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + + + :return: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this InlineDocumentSignerIntegrationData. + + + :param integration: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + + + :return: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this InlineDocumentSignerIntegrationData. + + + :param integration_data: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineDocumentSignerIntegrationData): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_integration_data.py b/signrequest_client/models/inline_integration_data.py new file mode 100644 index 0000000..9a3565f --- /dev/null +++ b/signrequest_client/models/inline_integration_data.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineIntegrationData(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, integration=None, integration_data=None): # noqa: E501 + """InlineIntegrationData - a model defined in Swagger""" # noqa: E501 + + self._integration = None + self._integration_data = None + self.discriminator = None + + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def integration(self): + """Gets the integration of this InlineIntegrationData. # noqa: E501 + + + :return: The integration of this InlineIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this InlineIntegrationData. + + + :param integration: The integration of this InlineIntegrationData. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this InlineIntegrationData. # noqa: E501 + + + :return: The integration_data of this InlineIntegrationData. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this InlineIntegrationData. + + + :param integration_data: The integration_data of this InlineIntegrationData. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineIntegrationData): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_prefill_tags.py b/signrequest_client/models/inline_prefill_tags.py new file mode 100644 index 0000000..53412db --- /dev/null +++ b/signrequest_client/models/inline_prefill_tags.py @@ -0,0 +1,192 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlinePrefillTags(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'external_id': 'str', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date' + } + + attribute_map = { + 'external_id': 'external_id', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value' + } + + def __init__(self, external_id=None, text=None, checkbox_value=None, date_value=None): # noqa: E501 + """InlinePrefillTags - a model defined in Swagger""" # noqa: E501 + + self._external_id = None + self._text = None + self._checkbox_value = None + self._date_value = None + self.discriminator = None + + if external_id is not None: + self.external_id = external_id + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this InlinePrefillTags. # noqa: E501 + + + :return: The external_id of this InlinePrefillTags. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this InlinePrefillTags. + + + :param external_id: The external_id of this InlinePrefillTags. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def text(self): + """Gets the text of this InlinePrefillTags. # noqa: E501 + + + :return: The text of this InlinePrefillTags. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this InlinePrefillTags. + + + :param text: The text of this InlinePrefillTags. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this InlinePrefillTags. # noqa: E501 + + + :return: The checkbox_value of this InlinePrefillTags. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this InlinePrefillTags. + + + :param checkbox_value: The checkbox_value of this InlinePrefillTags. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this InlinePrefillTags. # noqa: E501 + + + :return: The date_value of this InlinePrefillTags. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this InlinePrefillTags. + + + :param date_value: The date_value of this InlinePrefillTags. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlinePrefillTags): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200.py b/signrequest_client/models/inline_response_200.py new file mode 100644 index 0000000..d41c2ad --- /dev/null +++ b/signrequest_client/models/inline_response_200.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.auth_token import AuthToken # noqa: F401,E501 + + +class InlineResponse200(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[AuthToken]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse200 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse200. # noqa: E501 + + + :return: The count of this InlineResponse200. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse200. + + + :param count: The count of this InlineResponse200. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse200. # noqa: E501 + + + :return: The next of this InlineResponse200. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse200. + + + :param next: The next of this InlineResponse200. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse200. # noqa: E501 + + + :return: The previous of this InlineResponse200. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse200. + + + :param previous: The previous of this InlineResponse200. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse200. # noqa: E501 + + + :return: The results of this InlineResponse200. # noqa: E501 + :rtype: list[AuthToken] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse200. + + + :param results: The results of this InlineResponse200. # noqa: E501 + :type: list[AuthToken] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse200): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_1.py b/signrequest_client/models/inline_response_200_1.py new file mode 100644 index 0000000..9cde98c --- /dev/null +++ b/signrequest_client/models/inline_response_200_1.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 + + +class InlineResponse2001(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[DocumentAttachment]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2001 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2001. # noqa: E501 + + + :return: The count of this InlineResponse2001. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2001. + + + :param count: The count of this InlineResponse2001. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2001. # noqa: E501 + + + :return: The next of this InlineResponse2001. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2001. + + + :param next: The next of this InlineResponse2001. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2001. # noqa: E501 + + + :return: The previous of this InlineResponse2001. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2001. + + + :param previous: The previous of this InlineResponse2001. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2001. # noqa: E501 + + + :return: The results of this InlineResponse2001. # noqa: E501 + :rtype: list[DocumentAttachment] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2001. + + + :param results: The results of this InlineResponse2001. # noqa: E501 + :type: list[DocumentAttachment] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2001): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_2.py b/signrequest_client/models/inline_response_200_2.py new file mode 100644 index 0000000..cc431c6 --- /dev/null +++ b/signrequest_client/models/inline_response_200_2.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document_search import DocumentSearch # noqa: F401,E501 + + +class InlineResponse2002(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[DocumentSearch]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2002 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2002. # noqa: E501 + + + :return: The count of this InlineResponse2002. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2002. + + + :param count: The count of this InlineResponse2002. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2002. # noqa: E501 + + + :return: The next of this InlineResponse2002. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2002. + + + :param next: The next of this InlineResponse2002. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2002. # noqa: E501 + + + :return: The previous of this InlineResponse2002. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2002. + + + :param previous: The previous of this InlineResponse2002. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2002. # noqa: E501 + + + :return: The results of this InlineResponse2002. # noqa: E501 + :rtype: list[DocumentSearch] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2002. + + + :param results: The results of this InlineResponse2002. # noqa: E501 + :type: list[DocumentSearch] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2002): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_3.py b/signrequest_client/models/inline_response_200_3.py new file mode 100644 index 0000000..2dfba17 --- /dev/null +++ b/signrequest_client/models/inline_response_200_3.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document import Document # noqa: F401,E501 + + +class InlineResponse2003(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Document]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2003 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2003. # noqa: E501 + + + :return: The count of this InlineResponse2003. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2003. + + + :param count: The count of this InlineResponse2003. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2003. # noqa: E501 + + + :return: The next of this InlineResponse2003. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2003. + + + :param next: The next of this InlineResponse2003. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2003. # noqa: E501 + + + :return: The previous of this InlineResponse2003. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2003. + + + :param previous: The previous of this InlineResponse2003. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2003. # noqa: E501 + + + :return: The results of this InlineResponse2003. # noqa: E501 + :rtype: list[Document] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2003. + + + :param results: The results of this InlineResponse2003. # noqa: E501 + :type: list[Document] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2003): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_4.py b/signrequest_client/models/inline_response_200_4.py new file mode 100644 index 0000000..3c456cb --- /dev/null +++ b/signrequest_client/models/inline_response_200_4.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.event import Event # noqa: F401,E501 + + +class InlineResponse2004(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Event]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2004 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2004. # noqa: E501 + + + :return: The count of this InlineResponse2004. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2004. + + + :param count: The count of this InlineResponse2004. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2004. # noqa: E501 + + + :return: The next of this InlineResponse2004. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2004. + + + :param next: The next of this InlineResponse2004. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2004. # noqa: E501 + + + :return: The previous of this InlineResponse2004. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2004. + + + :param previous: The previous of this InlineResponse2004. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2004. # noqa: E501 + + + :return: The results of this InlineResponse2004. # noqa: E501 + :rtype: list[Event] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2004. + + + :param results: The results of this InlineResponse2004. # noqa: E501 + :type: list[Event] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2004): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_5.py b/signrequest_client/models/inline_response_200_5.py new file mode 100644 index 0000000..be9caff --- /dev/null +++ b/signrequest_client/models/inline_response_200_5.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.sign_request import SignRequest # noqa: F401,E501 + + +class InlineResponse2005(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[SignRequest]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2005 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2005. # noqa: E501 + + + :return: The count of this InlineResponse2005. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2005. + + + :param count: The count of this InlineResponse2005. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2005. # noqa: E501 + + + :return: The next of this InlineResponse2005. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2005. + + + :param next: The next of this InlineResponse2005. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2005. # noqa: E501 + + + :return: The previous of this InlineResponse2005. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2005. + + + :param previous: The previous of this InlineResponse2005. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2005. # noqa: E501 + + + :return: The results of this InlineResponse2005. # noqa: E501 + :rtype: list[SignRequest] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2005. + + + :param results: The results of this InlineResponse2005. # noqa: E501 + :type: list[SignRequest] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2005): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_6.py b/signrequest_client/models/inline_response_200_6.py new file mode 100644 index 0000000..934ee44 --- /dev/null +++ b/signrequest_client/models/inline_response_200_6.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.team_member import TeamMember # noqa: F401,E501 + + +class InlineResponse2006(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[TeamMember]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2006 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2006. # noqa: E501 + + + :return: The count of this InlineResponse2006. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2006. + + + :param count: The count of this InlineResponse2006. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2006. # noqa: E501 + + + :return: The next of this InlineResponse2006. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2006. + + + :param next: The next of this InlineResponse2006. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2006. # noqa: E501 + + + :return: The previous of this InlineResponse2006. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2006. + + + :param previous: The previous of this InlineResponse2006. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2006. # noqa: E501 + + + :return: The results of this InlineResponse2006. # noqa: E501 + :rtype: list[TeamMember] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2006. + + + :param results: The results of this InlineResponse2006. # noqa: E501 + :type: list[TeamMember] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2006): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_7.py b/signrequest_client/models/inline_response_200_7.py new file mode 100644 index 0000000..6995f30 --- /dev/null +++ b/signrequest_client/models/inline_response_200_7.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.team import Team # noqa: F401,E501 + + +class InlineResponse2007(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Team]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2007 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2007. # noqa: E501 + + + :return: The count of this InlineResponse2007. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2007. + + + :param count: The count of this InlineResponse2007. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2007. # noqa: E501 + + + :return: The next of this InlineResponse2007. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2007. + + + :param next: The next of this InlineResponse2007. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2007. # noqa: E501 + + + :return: The previous of this InlineResponse2007. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2007. + + + :param previous: The previous of this InlineResponse2007. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2007. # noqa: E501 + + + :return: The results of this InlineResponse2007. # noqa: E501 + :rtype: list[Team] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2007. + + + :param results: The results of this InlineResponse2007. # noqa: E501 + :type: list[Team] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2007): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_8.py b/signrequest_client/models/inline_response_200_8.py new file mode 100644 index 0000000..62d49ed --- /dev/null +++ b/signrequest_client/models/inline_response_200_8.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.template import Template # noqa: F401,E501 + + +class InlineResponse2008(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[Template]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2008 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2008. # noqa: E501 + + + :return: The count of this InlineResponse2008. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2008. + + + :param count: The count of this InlineResponse2008. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2008. # noqa: E501 + + + :return: The next of this InlineResponse2008. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2008. + + + :param next: The next of this InlineResponse2008. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2008. # noqa: E501 + + + :return: The previous of this InlineResponse2008. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2008. + + + :param previous: The previous of this InlineResponse2008. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2008. # noqa: E501 + + + :return: The results of this InlineResponse2008. # noqa: E501 + :rtype: list[Template] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2008. + + + :param results: The results of this InlineResponse2008. # noqa: E501 + :type: list[Template] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2008): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_200_9.py b/signrequest_client/models/inline_response_200_9.py new file mode 100644 index 0000000..4a6b52b --- /dev/null +++ b/signrequest_client/models/inline_response_200_9.py @@ -0,0 +1,194 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.webhook_subscription import WebhookSubscription # noqa: F401,E501 + + +class InlineResponse2009(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'count': 'int', + 'next': 'str', + 'previous': 'str', + 'results': 'list[WebhookSubscription]' + } + + attribute_map = { + 'count': 'count', + 'next': 'next', + 'previous': 'previous', + 'results': 'results' + } + + def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 + """InlineResponse2009 - a model defined in Swagger""" # noqa: E501 + + self._count = None + self._next = None + self._previous = None + self._results = None + self.discriminator = None + + self.count = count + if next is not None: + self.next = next + if previous is not None: + self.previous = previous + self.results = results + + @property + def count(self): + """Gets the count of this InlineResponse2009. # noqa: E501 + + + :return: The count of this InlineResponse2009. # noqa: E501 + :rtype: int + """ + return self._count + + @count.setter + def count(self, count): + """Sets the count of this InlineResponse2009. + + + :param count: The count of this InlineResponse2009. # noqa: E501 + :type: int + """ + if count is None: + raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 + + self._count = count + + @property + def next(self): + """Gets the next of this InlineResponse2009. # noqa: E501 + + + :return: The next of this InlineResponse2009. # noqa: E501 + :rtype: str + """ + return self._next + + @next.setter + def next(self, next): + """Sets the next of this InlineResponse2009. + + + :param next: The next of this InlineResponse2009. # noqa: E501 + :type: str + """ + + self._next = next + + @property + def previous(self): + """Gets the previous of this InlineResponse2009. # noqa: E501 + + + :return: The previous of this InlineResponse2009. # noqa: E501 + :rtype: str + """ + return self._previous + + @previous.setter + def previous(self, previous): + """Sets the previous of this InlineResponse2009. + + + :param previous: The previous of this InlineResponse2009. # noqa: E501 + :type: str + """ + + self._previous = previous + + @property + def results(self): + """Gets the results of this InlineResponse2009. # noqa: E501 + + + :return: The results of this InlineResponse2009. # noqa: E501 + :rtype: list[WebhookSubscription] + """ + return self._results + + @results.setter + def results(self, results): + """Sets the results of this InlineResponse2009. + + + :param results: The results of this InlineResponse2009. # noqa: E501 + :type: list[WebhookSubscription] + """ + if results is None: + raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 + + self._results = results + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2009): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_201.py b/signrequest_client/models/inline_response_201.py new file mode 100644 index 0000000..7d8cb87 --- /dev/null +++ b/signrequest_client/models/inline_response_201.py @@ -0,0 +1,146 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineResponse201(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'cancelled': 'bool', + 'detail': 'str' + } + + attribute_map = { + 'cancelled': 'cancelled', + 'detail': 'detail' + } + + def __init__(self, cancelled=None, detail=None): # noqa: E501 + """InlineResponse201 - a model defined in Swagger""" # noqa: E501 + + self._cancelled = None + self._detail = None + self.discriminator = None + + self.cancelled = cancelled + self.detail = detail + + @property + def cancelled(self): + """Gets the cancelled of this InlineResponse201. # noqa: E501 + + + :return: The cancelled of this InlineResponse201. # noqa: E501 + :rtype: bool + """ + return self._cancelled + + @cancelled.setter + def cancelled(self, cancelled): + """Sets the cancelled of this InlineResponse201. + + + :param cancelled: The cancelled of this InlineResponse201. # noqa: E501 + :type: bool + """ + if cancelled is None: + raise ValueError("Invalid value for `cancelled`, must not be `None`") # noqa: E501 + + self._cancelled = cancelled + + @property + def detail(self): + """Gets the detail of this InlineResponse201. # noqa: E501 + + + :return: The detail of this InlineResponse201. # noqa: E501 + :rtype: str + """ + return self._detail + + @detail.setter + def detail(self, detail): + """Sets the detail of this InlineResponse201. + + + :param detail: The detail of this InlineResponse201. # noqa: E501 + :type: str + """ + if detail is None: + raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 + allowed_values = ["OK"] # noqa: E501 + if detail not in allowed_values: + raise ValueError( + "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 + .format(detail, allowed_values) + ) + + self._detail = detail + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse201): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_response_201_1.py b/signrequest_client/models/inline_response_201_1.py new file mode 100644 index 0000000..dd6782d --- /dev/null +++ b/signrequest_client/models/inline_response_201_1.py @@ -0,0 +1,119 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineResponse2011(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'detail': 'str' + } + + attribute_map = { + 'detail': 'detail' + } + + def __init__(self, detail=None): # noqa: E501 + """InlineResponse2011 - a model defined in Swagger""" # noqa: E501 + + self._detail = None + self.discriminator = None + + self.detail = detail + + @property + def detail(self): + """Gets the detail of this InlineResponse2011. # noqa: E501 + + + :return: The detail of this InlineResponse2011. # noqa: E501 + :rtype: str + """ + return self._detail + + @detail.setter + def detail(self, detail): + """Sets the detail of this InlineResponse2011. + + + :param detail: The detail of this InlineResponse2011. # noqa: E501 + :type: str + """ + if detail is None: + raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 + allowed_values = ["OK"] # noqa: E501 + if detail not in allowed_values: + raise ValueError( + "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 + .format(detail, allowed_values) + ) + + self._detail = detail + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineResponse2011): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_sign_request.py b/signrequest_client/models/inline_sign_request.py new file mode 100644 index 0000000..637c059 --- /dev/null +++ b/signrequest_client/models/inline_sign_request.py @@ -0,0 +1,605 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_client.models.signer import Signer # noqa: F401,E501 + + +class InlineSignRequest(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who=None, send_reminders=None, signers=None, uuid=None): # noqa: E501 + """InlineSignRequest - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self.discriminator = None + + if from_email is not None: + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + if signers is not None: + self.signers = signers + if uuid is not None: + self.uuid = uuid + + @property + def from_email(self): + """Gets the from_email of this InlineSignRequest. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this InlineSignRequest. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this InlineSignRequest. # noqa: E501 + :type: str + """ + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this InlineSignRequest. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this InlineSignRequest. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this InlineSignRequest. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) < 1: + raise ValueError("Invalid value for `from_email_name`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this InlineSignRequest. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this InlineSignRequest. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this InlineSignRequest. # noqa: E501 + + + :return: The prepare_url of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this InlineSignRequest. + + + :param prepare_url: The prepare_url of this InlineSignRequest. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this InlineSignRequest. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this InlineSignRequest. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this InlineSignRequest. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) < 1: + raise ValueError("Invalid value for `redirect_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this InlineSignRequest. # noqa: E501 + + + :return: The required_attachments of this InlineSignRequest. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this InlineSignRequest. + + + :param required_attachments: The required_attachments of this InlineSignRequest. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this InlineSignRequest. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this InlineSignRequest. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this InlineSignRequest. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this InlineSignRequest. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this InlineSignRequest. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this InlineSignRequest. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this InlineSignRequest. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this InlineSignRequest. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this InlineSignRequest. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this InlineSignRequest. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this InlineSignRequest. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this InlineSignRequest. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this InlineSignRequest. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this InlineSignRequest. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this InlineSignRequest. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) < 1: + raise ValueError("Invalid value for `subject`, length must be greater than or equal to `1`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this InlineSignRequest. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this InlineSignRequest. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this InlineSignRequest. # noqa: E501 + :type: str + """ + if message is not None and len(message) < 1: + raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 + + self._message = message + + @property + def who(self): + """Gets the who of this InlineSignRequest. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this InlineSignRequest. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this InlineSignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this InlineSignRequest. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this InlineSignRequest. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this InlineSignRequest. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this InlineSignRequest. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this InlineSignRequest. # noqa: E501 + + + :return: The signers of this InlineSignRequest. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this InlineSignRequest. + + + :param signers: The signers of this InlineSignRequest. # noqa: E501 + :type: list[Signer] + """ + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this InlineSignRequest. # noqa: E501 + + + :return: The uuid of this InlineSignRequest. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this InlineSignRequest. + + + :param uuid: The uuid of this InlineSignRequest. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineSignRequest): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_team.py b/signrequest_client/models/inline_team.py new file mode 100644 index 0000000..169367e --- /dev/null +++ b/signrequest_client/models/inline_team.py @@ -0,0 +1,170 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InlineTeam(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'subdomain': 'str', + 'url': 'str' + } + + attribute_map = { + 'name': 'name', + 'subdomain': 'subdomain', + 'url': 'url' + } + + def __init__(self, name=None, subdomain=None, url=None): # noqa: E501 + """InlineTeam - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._subdomain = None + self._url = None + self.discriminator = None + + if name is not None: + self.name = name + if subdomain is not None: + self.subdomain = subdomain + if url is not None: + self.url = url + + @property + def name(self): + """Gets the name of this InlineTeam. # noqa: E501 + + + :return: The name of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this InlineTeam. + + + :param name: The name of this InlineTeam. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def subdomain(self): + """Gets the subdomain of this InlineTeam. # noqa: E501 + + + :return: The subdomain of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this InlineTeam. + + + :param subdomain: The subdomain of this InlineTeam. # noqa: E501 + :type: str + """ + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 + raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 + + self._subdomain = subdomain + + @property + def url(self): + """Gets the url of this InlineTeam. # noqa: E501 + + + :return: The url of this InlineTeam. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this InlineTeam. + + + :param url: The url of this InlineTeam. # noqa: E501 + :type: str + """ + + self._url = url + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineTeam): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/inline_team_member.py b/signrequest_client/models/inline_team_member.py new file mode 100644 index 0000000..18bc415 --- /dev/null +++ b/signrequest_client/models/inline_team_member.py @@ -0,0 +1,246 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.user import User # noqa: F401,E501 + + +class InlineTeamMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'url': 'str', + 'user': 'User', + 'is_admin': 'bool', + 'is_active': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'uuid': 'uuid', + 'url': 'url', + 'user': 'user', + 'is_admin': 'is_admin', + 'is_active': 'is_active', + 'is_owner': 'is_owner' + } + + def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 + """InlineTeamMember - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._url = None + self._user = None + self._is_admin = None + self._is_active = None + self._is_owner = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if user is not None: + self.user = user + if is_admin is not None: + self.is_admin = is_admin + if is_active is not None: + self.is_active = is_active + if is_owner is not None: + self.is_owner = is_owner + + @property + def uuid(self): + """Gets the uuid of this InlineTeamMember. # noqa: E501 + + + :return: The uuid of this InlineTeamMember. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this InlineTeamMember. + + + :param uuid: The uuid of this InlineTeamMember. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this InlineTeamMember. # noqa: E501 + + + :return: The url of this InlineTeamMember. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this InlineTeamMember. + + + :param url: The url of this InlineTeamMember. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def user(self): + """Gets the user of this InlineTeamMember. # noqa: E501 + + + :return: The user of this InlineTeamMember. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this InlineTeamMember. + + + :param user: The user of this InlineTeamMember. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def is_admin(self): + """Gets the is_admin of this InlineTeamMember. # noqa: E501 + + + :return: The is_admin of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this InlineTeamMember. + + + :param is_admin: The is_admin of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_active(self): + """Gets the is_active of this InlineTeamMember. # noqa: E501 + + + :return: The is_active of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_active + + @is_active.setter + def is_active(self, is_active): + """Sets the is_active of this InlineTeamMember. + + + :param is_active: The is_active of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_active = is_active + + @property + def is_owner(self): + """Gets the is_owner of this InlineTeamMember. # noqa: E501 + + + :return: The is_owner of this InlineTeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this InlineTeamMember. + + + :param is_owner: The is_owner of this InlineTeamMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InlineTeamMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/invite_member.py b/signrequest_client/models/invite_member.py new file mode 100644 index 0000000..14bf9a6 --- /dev/null +++ b/signrequest_client/models/invite_member.py @@ -0,0 +1,167 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class InviteMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'is_admin': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'email': 'email', + 'is_admin': 'is_admin', + 'is_owner': 'is_owner' + } + + def __init__(self, email=None, is_admin=False, is_owner=False): # noqa: E501 + """InviteMember - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._is_admin = None + self._is_owner = None + self.discriminator = None + + self.email = email + if is_admin is not None: + self.is_admin = is_admin + if is_owner is not None: + self.is_owner = is_owner + + @property + def email(self): + """Gets the email of this InviteMember. # noqa: E501 + + + :return: The email of this InviteMember. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this InviteMember. + + + :param email: The email of this InviteMember. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def is_admin(self): + """Gets the is_admin of this InviteMember. # noqa: E501 + + + :return: The is_admin of this InviteMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this InviteMember. + + + :param is_admin: The is_admin of this InviteMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_owner(self): + """Gets the is_owner of this InviteMember. # noqa: E501 + + + :return: The is_owner of this InviteMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this InviteMember. + + + :param is_owner: The is_owner of this InviteMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, InviteMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/placeholder.py b/signrequest_client/models/placeholder.py new file mode 100644 index 0000000..1fe7897 --- /dev/null +++ b/signrequest_client/models/placeholder.py @@ -0,0 +1,306 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class Placeholder(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'type': 'str', + 'page_index': 'int', + 'prefill': 'bool', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date', + 'external_id': 'str' + } + + attribute_map = { + 'uuid': 'uuid', + 'type': 'type', + 'page_index': 'page_index', + 'prefill': 'prefill', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value', + 'external_id': 'external_id' + } + + def __init__(self, uuid=None, type=None, page_index=None, prefill=None, text=None, checkbox_value=None, date_value=None, external_id=None): # noqa: E501 + """Placeholder - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._type = None + self._page_index = None + self._prefill = None + self._text = None + self._checkbox_value = None + self._date_value = None + self._external_id = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if type is not None: + self.type = type + self.page_index = page_index + self.prefill = prefill + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + if external_id is not None: + self.external_id = external_id + + @property + def uuid(self): + """Gets the uuid of this Placeholder. # noqa: E501 + + + :return: The uuid of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Placeholder. + + + :param uuid: The uuid of this Placeholder. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def type(self): + """Gets the type of this Placeholder. # noqa: E501 + + + :return: The type of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._type + + @type.setter + def type(self, type): + """Sets the type of this Placeholder. + + + :param type: The type of this Placeholder. # noqa: E501 + :type: str + """ + allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 + if type not in allowed_values: + raise ValueError( + "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 + .format(type, allowed_values) + ) + + self._type = type + + @property + def page_index(self): + """Gets the page_index of this Placeholder. # noqa: E501 + + + :return: The page_index of this Placeholder. # noqa: E501 + :rtype: int + """ + return self._page_index + + @page_index.setter + def page_index(self, page_index): + """Sets the page_index of this Placeholder. + + + :param page_index: The page_index of this Placeholder. # noqa: E501 + :type: int + """ + if page_index is None: + raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 + + self._page_index = page_index + + @property + def prefill(self): + """Gets the prefill of this Placeholder. # noqa: E501 + + + :return: The prefill of this Placeholder. # noqa: E501 + :rtype: bool + """ + return self._prefill + + @prefill.setter + def prefill(self, prefill): + """Sets the prefill of this Placeholder. + + + :param prefill: The prefill of this Placeholder. # noqa: E501 + :type: bool + """ + if prefill is None: + raise ValueError("Invalid value for `prefill`, must not be `None`") # noqa: E501 + + self._prefill = prefill + + @property + def text(self): + """Gets the text of this Placeholder. # noqa: E501 + + + :return: The text of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this Placeholder. + + + :param text: The text of this Placeholder. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this Placeholder. # noqa: E501 + + + :return: The checkbox_value of this Placeholder. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this Placeholder. + + + :param checkbox_value: The checkbox_value of this Placeholder. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this Placeholder. # noqa: E501 + + + :return: The date_value of this Placeholder. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this Placeholder. + + + :param date_value: The date_value of this Placeholder. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this Placeholder. # noqa: E501 + + + :return: The external_id of this Placeholder. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this Placeholder. + + + :param external_id: The external_id of this Placeholder. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Placeholder): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/required_attachment.py b/signrequest_client/models/required_attachment.py new file mode 100644 index 0000000..57c16dc --- /dev/null +++ b/signrequest_client/models/required_attachment.py @@ -0,0 +1,145 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class RequiredAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'uuid': 'str' + } + + attribute_map = { + 'name': 'name', + 'uuid': 'uuid' + } + + def __init__(self, name=None, uuid=None): # noqa: E501 + """RequiredAttachment - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._uuid = None + self.discriminator = None + + self.name = name + if uuid is not None: + self.uuid = uuid + + @property + def name(self): + """Gets the name of this RequiredAttachment. # noqa: E501 + + + :return: The name of this RequiredAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this RequiredAttachment. + + + :param name: The name of this RequiredAttachment. # noqa: E501 + :type: str + """ + if name is None: + raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def uuid(self): + """Gets the uuid of this RequiredAttachment. # noqa: E501 + + + :return: The uuid of this RequiredAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this RequiredAttachment. + + + :param uuid: The uuid of this RequiredAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, RequiredAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/sign_request.py b/signrequest_client/models/sign_request.py new file mode 100644 index 0000000..a92a42f --- /dev/null +++ b/signrequest_client/models/sign_request.py @@ -0,0 +1,719 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_client.models.signer import Signer # noqa: F401,E501 + + +class SignRequest(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str', + 'url': 'str', + 'document': 'str', + 'integration': 'str', + 'integration_data': 'str' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid', + 'url': 'url', + 'document': 'document', + 'integration': 'integration', + 'integration_data': 'integration_data' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None): # noqa: E501 + """SignRequest - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self._url = None + self._document = None + self._integration = None + self._integration_data = None + self.discriminator = None + + if from_email is not None: + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + self.signers = signers + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + self.document = document + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + + @property + def from_email(self): + """Gets the from_email of this SignRequest. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this SignRequest. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this SignRequest. # noqa: E501 + :type: str + """ + if from_email is not None and len(from_email) > 255: + raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this SignRequest. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this SignRequest. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this SignRequest. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) > 255: + raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this SignRequest. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this SignRequest. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this SignRequest. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this SignRequest. # noqa: E501 + + + :return: The prepare_url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this SignRequest. + + + :param prepare_url: The prepare_url of this SignRequest. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this SignRequest. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this SignRequest. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this SignRequest. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this SignRequest. # noqa: E501 + + Attachments that signers are required to upload # noqa: E501 + + :return: The required_attachments of this SignRequest. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this SignRequest. + + Attachments that signers are required to upload # noqa: E501 + + :param required_attachments: The required_attachments of this SignRequest. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this SignRequest. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this SignRequest. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this SignRequest. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this SignRequest. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this SignRequest. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this SignRequest. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this SignRequest. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this SignRequest. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this SignRequest. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this SignRequest. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this SignRequest. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this SignRequest. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this SignRequest. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this SignRequest. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this SignRequest. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this SignRequest. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) > 512: + raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this SignRequest. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this SignRequest. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this SignRequest. # noqa: E501 + :type: str + """ + + self._message = message + + @property + def who(self): + """Gets the who of this SignRequest. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this SignRequest. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this SignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this SignRequest. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this SignRequest. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this SignRequest. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this SignRequest. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this SignRequest. # noqa: E501 + + + :return: The signers of this SignRequest. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this SignRequest. + + + :param signers: The signers of this SignRequest. # noqa: E501 + :type: list[Signer] + """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this SignRequest. # noqa: E501 + + + :return: The uuid of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignRequest. + + + :param uuid: The uuid of this SignRequest. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this SignRequest. # noqa: E501 + + + :return: The url of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this SignRequest. + + + :param url: The url of this SignRequest. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def document(self): + """Gets the document of this SignRequest. # noqa: E501 + + + :return: The document of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this SignRequest. + + + :param document: The document of this SignRequest. # noqa: E501 + :type: str + """ + if document is None: + raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 + + self._document = document + + @property + def integration(self): + """Gets the integration of this SignRequest. # noqa: E501 + + + :return: The integration of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this SignRequest. + + + :param integration: The integration of this SignRequest. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this SignRequest. # noqa: E501 + + + :return: The integration_data of this SignRequest. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this SignRequest. + + + :param integration_data: The integration_data of this SignRequest. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignRequest): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/sign_request_quick_create.py b/signrequest_client/models/sign_request_quick_create.py new file mode 100644 index 0000000..760d772 --- /dev/null +++ b/signrequest_client/models/sign_request_quick_create.py @@ -0,0 +1,1093 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.file_from_sf import FileFromSf # noqa: F401,E501 +from signrequest_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 +from signrequest_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 +from signrequest_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 +from signrequest_client.models.signer import Signer # noqa: F401,E501 + + +class SignRequestQuickCreate(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'from_email': 'str', + 'from_email_name': 'str', + 'is_being_prepared': 'bool', + 'prepare_url': 'str', + 'redirect_url': 'str', + 'required_attachments': 'list[RequiredAttachment]', + 'disable_attachments': 'bool', + 'disable_text_signatures': 'bool', + 'disable_text': 'bool', + 'disable_date': 'bool', + 'disable_emails': 'bool', + 'disable_upload_signatures': 'bool', + 'subject': 'str', + 'message': 'str', + 'who': 'str', + 'send_reminders': 'bool', + 'signers': 'list[Signer]', + 'uuid': 'str', + 'url': 'str', + 'document': 'str', + 'integration': 'str', + 'integration_data': 'str', + 'name': 'str', + 'external_id': 'str', + 'frontend_id': 'str', + 'file': 'str', + 'file_from_url': 'str', + 'events_callback_url': 'str', + 'file_from_content': 'str', + 'file_from_content_name': 'str', + 'template': 'str', + 'prefill_tags': 'list[InlinePrefillTags]', + 'integrations': 'list[InlineIntegrationData]', + 'file_from_sf': 'FileFromSf', + 'auto_delete_days': 'int' + } + + attribute_map = { + 'from_email': 'from_email', + 'from_email_name': 'from_email_name', + 'is_being_prepared': 'is_being_prepared', + 'prepare_url': 'prepare_url', + 'redirect_url': 'redirect_url', + 'required_attachments': 'required_attachments', + 'disable_attachments': 'disable_attachments', + 'disable_text_signatures': 'disable_text_signatures', + 'disable_text': 'disable_text', + 'disable_date': 'disable_date', + 'disable_emails': 'disable_emails', + 'disable_upload_signatures': 'disable_upload_signatures', + 'subject': 'subject', + 'message': 'message', + 'who': 'who', + 'send_reminders': 'send_reminders', + 'signers': 'signers', + 'uuid': 'uuid', + 'url': 'url', + 'document': 'document', + 'integration': 'integration', + 'integration_data': 'integration_data', + 'name': 'name', + 'external_id': 'external_id', + 'frontend_id': 'frontend_id', + 'file': 'file', + 'file_from_url': 'file_from_url', + 'events_callback_url': 'events_callback_url', + 'file_from_content': 'file_from_content', + 'file_from_content_name': 'file_from_content_name', + 'template': 'template', + 'prefill_tags': 'prefill_tags', + 'integrations': 'integrations', + 'file_from_sf': 'file_from_sf', + 'auto_delete_days': 'auto_delete_days' + } + + def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None): # noqa: E501 + """SignRequestQuickCreate - a model defined in Swagger""" # noqa: E501 + + self._from_email = None + self._from_email_name = None + self._is_being_prepared = None + self._prepare_url = None + self._redirect_url = None + self._required_attachments = None + self._disable_attachments = None + self._disable_text_signatures = None + self._disable_text = None + self._disable_date = None + self._disable_emails = None + self._disable_upload_signatures = None + self._subject = None + self._message = None + self._who = None + self._send_reminders = None + self._signers = None + self._uuid = None + self._url = None + self._document = None + self._integration = None + self._integration_data = None + self._name = None + self._external_id = None + self._frontend_id = None + self._file = None + self._file_from_url = None + self._events_callback_url = None + self._file_from_content = None + self._file_from_content_name = None + self._template = None + self._prefill_tags = None + self._integrations = None + self._file_from_sf = None + self._auto_delete_days = None + self.discriminator = None + + if from_email is not None: + self.from_email = from_email + if from_email_name is not None: + self.from_email_name = from_email_name + if is_being_prepared is not None: + self.is_being_prepared = is_being_prepared + if prepare_url is not None: + self.prepare_url = prepare_url + if redirect_url is not None: + self.redirect_url = redirect_url + if required_attachments is not None: + self.required_attachments = required_attachments + if disable_attachments is not None: + self.disable_attachments = disable_attachments + if disable_text_signatures is not None: + self.disable_text_signatures = disable_text_signatures + if disable_text is not None: + self.disable_text = disable_text + if disable_date is not None: + self.disable_date = disable_date + if disable_emails is not None: + self.disable_emails = disable_emails + if disable_upload_signatures is not None: + self.disable_upload_signatures = disable_upload_signatures + if subject is not None: + self.subject = subject + if message is not None: + self.message = message + if who is not None: + self.who = who + if send_reminders is not None: + self.send_reminders = send_reminders + self.signers = signers + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if document is not None: + self.document = document + if integration is not None: + self.integration = integration + if integration_data is not None: + self.integration_data = integration_data + if name is not None: + self.name = name + if external_id is not None: + self.external_id = external_id + if frontend_id is not None: + self.frontend_id = frontend_id + if file is not None: + self.file = file + if file_from_url is not None: + self.file_from_url = file_from_url + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if file_from_content is not None: + self.file_from_content = file_from_content + if file_from_content_name is not None: + self.file_from_content_name = file_from_content_name + if template is not None: + self.template = template + if prefill_tags is not None: + self.prefill_tags = prefill_tags + if integrations is not None: + self.integrations = integrations + if file_from_sf is not None: + self.file_from_sf = file_from_sf + if auto_delete_days is not None: + self.auto_delete_days = auto_delete_days + + @property + def from_email(self): + """Gets the from_email of this SignRequestQuickCreate. # noqa: E501 + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :return: The from_email of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._from_email + + @from_email.setter + def from_email(self, from_email): + """Sets the from_email of this SignRequestQuickCreate. + + Email of user sending the SignRequest (must be a validated email) # noqa: E501 + + :param from_email: The from_email of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if from_email is not None and len(from_email) > 255: + raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 + if from_email is not None and len(from_email) < 1: + raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._from_email = from_email + + @property + def from_email_name(self): + """Gets the from_email_name of this SignRequestQuickCreate. # noqa: E501 + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :return: The from_email_name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._from_email_name + + @from_email_name.setter + def from_email_name(self, from_email_name): + """Sets the from_email_name of this SignRequestQuickCreate. + + Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 + + :param from_email_name: The from_email_name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if from_email_name is not None and len(from_email_name) > 255: + raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 + + self._from_email_name = from_email_name + + @property + def is_being_prepared(self): + """Gets the is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :return: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._is_being_prepared + + @is_being_prepared.setter + def is_being_prepared(self, is_being_prepared): + """Sets the is_being_prepared of this SignRequestQuickCreate. + + Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 + + :param is_being_prepared: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._is_being_prepared = is_being_prepared + + @property + def prepare_url(self): + """Gets the prepare_url of this SignRequestQuickCreate. # noqa: E501 + + + :return: The prepare_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._prepare_url + + @prepare_url.setter + def prepare_url(self, prepare_url): + """Sets the prepare_url of this SignRequestQuickCreate. + + + :param prepare_url: The prepare_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if prepare_url is not None and len(prepare_url) < 1: + raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._prepare_url = prepare_url + + @property + def redirect_url(self): + """Gets the redirect_url of this SignRequestQuickCreate. # noqa: E501 + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :return: The redirect_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this SignRequestQuickCreate. + + URL at which SignRequest will redirect to when a document is signed # noqa: E501 + + :param redirect_url: The redirect_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def required_attachments(self): + """Gets the required_attachments of this SignRequestQuickCreate. # noqa: E501 + + Attachments that signers are required to upload # noqa: E501 + + :return: The required_attachments of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[RequiredAttachment] + """ + return self._required_attachments + + @required_attachments.setter + def required_attachments(self, required_attachments): + """Sets the required_attachments of this SignRequestQuickCreate. + + Attachments that signers are required to upload # noqa: E501 + + :param required_attachments: The required_attachments of this SignRequestQuickCreate. # noqa: E501 + :type: list[RequiredAttachment] + """ + + self._required_attachments = required_attachments + + @property + def disable_attachments(self): + """Gets the disable_attachments of this SignRequestQuickCreate. # noqa: E501 + + Disable uploading/adding of attachments # noqa: E501 + + :return: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_attachments + + @disable_attachments.setter + def disable_attachments(self, disable_attachments): + """Sets the disable_attachments of this SignRequestQuickCreate. + + Disable uploading/adding of attachments # noqa: E501 + + :param disable_attachments: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_attachments = disable_attachments + + @property + def disable_text_signatures(self): + """Gets the disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :return: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_text_signatures + + @disable_text_signatures.setter + def disable_text_signatures(self, disable_text_signatures): + """Sets the disable_text_signatures of this SignRequestQuickCreate. + + Disable usage of signatures generated by typing (text) # noqa: E501 + + :param disable_text_signatures: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_text_signatures = disable_text_signatures + + @property + def disable_text(self): + """Gets the disable_text of this SignRequestQuickCreate. # noqa: E501 + + Disable adding of text # noqa: E501 + + :return: The disable_text of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_text + + @disable_text.setter + def disable_text(self, disable_text): + """Sets the disable_text of this SignRequestQuickCreate. + + Disable adding of text # noqa: E501 + + :param disable_text: The disable_text of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_text = disable_text + + @property + def disable_date(self): + """Gets the disable_date of this SignRequestQuickCreate. # noqa: E501 + + Disable adding of dates # noqa: E501 + + :return: The disable_date of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_date + + @disable_date.setter + def disable_date(self, disable_date): + """Sets the disable_date of this SignRequestQuickCreate. + + Disable adding of dates # noqa: E501 + + :param disable_date: The disable_date of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_date = disable_date + + @property + def disable_emails(self): + """Gets the disable_emails of this SignRequestQuickCreate. # noqa: E501 + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :return: The disable_emails of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_emails + + @disable_emails.setter + def disable_emails(self, disable_emails): + """Sets the disable_emails of this SignRequestQuickCreate. + + Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 + + :param disable_emails: The disable_emails of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_emails = disable_emails + + @property + def disable_upload_signatures(self): + """Gets the disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + + Disable usage of uploaded signatures (images) # noqa: E501 + + :return: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._disable_upload_signatures + + @disable_upload_signatures.setter + def disable_upload_signatures(self, disable_upload_signatures): + """Sets the disable_upload_signatures of this SignRequestQuickCreate. + + Disable usage of uploaded signatures (images) # noqa: E501 + + :param disable_upload_signatures: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._disable_upload_signatures = disable_upload_signatures + + @property + def subject(self): + """Gets the subject of this SignRequestQuickCreate. # noqa: E501 + + Subject of SignRequest email # noqa: E501 + + :return: The subject of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._subject + + @subject.setter + def subject(self, subject): + """Sets the subject of this SignRequestQuickCreate. + + Subject of SignRequest email # noqa: E501 + + :param subject: The subject of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if subject is not None and len(subject) > 512: + raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 + + self._subject = subject + + @property + def message(self): + """Gets the message of this SignRequestQuickCreate. # noqa: E501 + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :return: The message of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this SignRequestQuickCreate. + + Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 + + :param message: The message of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._message = message + + @property + def who(self): + """Gets the who of this SignRequestQuickCreate. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this SignRequestQuickCreate. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def send_reminders(self): + """Gets the send_reminders of this SignRequestQuickCreate. # noqa: E501 + + Automatically remind signers to sign a document # noqa: E501 + + :return: The send_reminders of this SignRequestQuickCreate. # noqa: E501 + :rtype: bool + """ + return self._send_reminders + + @send_reminders.setter + def send_reminders(self, send_reminders): + """Sets the send_reminders of this SignRequestQuickCreate. + + Automatically remind signers to sign a document # noqa: E501 + + :param send_reminders: The send_reminders of this SignRequestQuickCreate. # noqa: E501 + :type: bool + """ + + self._send_reminders = send_reminders + + @property + def signers(self): + """Gets the signers of this SignRequestQuickCreate. # noqa: E501 + + + :return: The signers of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[Signer] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this SignRequestQuickCreate. + + + :param signers: The signers of this SignRequestQuickCreate. # noqa: E501 + :type: list[Signer] + """ + if signers is None: + raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 + + self._signers = signers + + @property + def uuid(self): + """Gets the uuid of this SignRequestQuickCreate. # noqa: E501 + + + :return: The uuid of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignRequestQuickCreate. + + + :param uuid: The uuid of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this SignRequestQuickCreate. # noqa: E501 + + + :return: The url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this SignRequestQuickCreate. + + + :param url: The url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def document(self): + """Gets the document of this SignRequestQuickCreate. # noqa: E501 + + + :return: The document of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._document + + @document.setter + def document(self, document): + """Sets the document of this SignRequestQuickCreate. + + + :param document: The document of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._document = document + + @property + def integration(self): + """Gets the integration of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integration of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this SignRequestQuickCreate. + + + :param integration: The integration of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def integration_data(self): + """Gets the integration_data of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integration_data of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._integration_data + + @integration_data.setter + def integration_data(self, integration_data): + """Sets the integration_data of this SignRequestQuickCreate. + + + :param integration_data: The integration_data of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._integration_data = integration_data + + @property + def name(self): + """Gets the name of this SignRequestQuickCreate. # noqa: E501 + + Defaults to filename, including extension # noqa: E501 + + :return: The name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this SignRequestQuickCreate. + + Defaults to filename, including extension # noqa: E501 + + :param name: The name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def external_id(self): + """Gets the external_id of this SignRequestQuickCreate. # noqa: E501 + + ID used to reference document in external system # noqa: E501 + + :return: The external_id of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this SignRequestQuickCreate. + + ID used to reference document in external system # noqa: E501 + + :param external_id: The external_id of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def frontend_id(self): + """Gets the frontend_id of this SignRequestQuickCreate. # noqa: E501 + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :return: The frontend_id of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._frontend_id + + @frontend_id.setter + def frontend_id(self, frontend_id): + """Sets the frontend_id of this SignRequestQuickCreate. + + Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 + + :param frontend_id: The frontend_id of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if frontend_id is not None and len(frontend_id) > 255: + raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 + + self._frontend_id = frontend_id + + @property + def file(self): + """Gets the file of this SignRequestQuickCreate. # noqa: E501 + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :return: The file of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this SignRequestQuickCreate. + + Temporary URL to original file, expires in five minutes # noqa: E501 + + :param file: The file of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def file_from_url(self): + """Gets the file_from_url of this SignRequestQuickCreate. # noqa: E501 + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :return: The file_from_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_url + + @file_from_url.setter + def file_from_url(self, file_from_url): + """Sets the file_from_url of this SignRequestQuickCreate. + + Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 + + :param file_from_url: The file_from_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if file_from_url is not None and len(file_from_url) > 2100: + raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._file_from_url = file_from_url + + @property + def events_callback_url(self): + """Gets the events_callback_url of this SignRequestQuickCreate. # noqa: E501 + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :return: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this SignRequestQuickCreate. + + URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 + + :param events_callback_url: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def file_from_content(self): + """Gets the file_from_content of this SignRequestQuickCreate. # noqa: E501 + + Base64 encoded document content # noqa: E501 + + :return: The file_from_content of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_content + + @file_from_content.setter + def file_from_content(self, file_from_content): + """Sets the file_from_content of this SignRequestQuickCreate. + + Base64 encoded document content # noqa: E501 + + :param file_from_content: The file_from_content of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file_from_content = file_from_content + + @property + def file_from_content_name(self): + """Gets the file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :return: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._file_from_content_name + + @file_from_content_name.setter + def file_from_content_name(self, file_from_content_name): + """Sets the file_from_content_name of this SignRequestQuickCreate. + + Filename, including extension. Required when using `file_from_content`. # noqa: E501 + + :param file_from_content_name: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._file_from_content_name = file_from_content_name + + @property + def template(self): + """Gets the template of this SignRequestQuickCreate. # noqa: E501 + + + :return: The template of this SignRequestQuickCreate. # noqa: E501 + :rtype: str + """ + return self._template + + @template.setter + def template(self, template): + """Sets the template of this SignRequestQuickCreate. + + + :param template: The template of this SignRequestQuickCreate. # noqa: E501 + :type: str + """ + + self._template = template + + @property + def prefill_tags(self): + """Gets the prefill_tags of this SignRequestQuickCreate. # noqa: E501 + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :return: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[InlinePrefillTags] + """ + return self._prefill_tags + + @prefill_tags.setter + def prefill_tags(self, prefill_tags): + """Sets the prefill_tags of this SignRequestQuickCreate. + + Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 + + :param prefill_tags: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 + :type: list[InlinePrefillTags] + """ + + self._prefill_tags = prefill_tags + + @property + def integrations(self): + """Gets the integrations of this SignRequestQuickCreate. # noqa: E501 + + + :return: The integrations of this SignRequestQuickCreate. # noqa: E501 + :rtype: list[InlineIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this SignRequestQuickCreate. + + + :param integrations: The integrations of this SignRequestQuickCreate. # noqa: E501 + :type: list[InlineIntegrationData] + """ + + self._integrations = integrations + + @property + def file_from_sf(self): + """Gets the file_from_sf of this SignRequestQuickCreate. # noqa: E501 + + + :return: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 + :rtype: FileFromSf + """ + return self._file_from_sf + + @file_from_sf.setter + def file_from_sf(self, file_from_sf): + """Sets the file_from_sf of this SignRequestQuickCreate. + + + :param file_from_sf: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 + :type: FileFromSf + """ + + self._file_from_sf = file_from_sf + + @property + def auto_delete_days(self): + """Gets the auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :return: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + :rtype: int + """ + return self._auto_delete_days + + @auto_delete_days.setter + def auto_delete_days(self, auto_delete_days): + """Sets the auto_delete_days of this SignRequestQuickCreate. + + Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 + + :param auto_delete_days: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 + :type: int + """ + if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 + if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 + raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 + + self._auto_delete_days = auto_delete_days + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignRequestQuickCreate): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/signer.py b/signrequest_client/models/signer.py new file mode 100644 index 0000000..1f3a309 --- /dev/null +++ b/signrequest_client/models/signer.py @@ -0,0 +1,985 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData # noqa: F401,E501 +from signrequest_client.models.signer_attachment import SignerAttachment # noqa: F401,E501 +from signrequest_client.models.signer_inputs import SignerInputs # noqa: F401,E501 + + +class Signer(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'display_name': 'str', + 'first_name': 'str', + 'last_name': 'str', + 'email_viewed': 'bool', + 'viewed': 'bool', + 'signed': 'bool', + 'downloaded': 'bool', + 'signed_on': 'datetime', + 'needs_to_sign': 'bool', + 'approve_only': 'bool', + 'notify_only': 'bool', + 'in_person': 'bool', + 'order': 'int', + 'language': 'str', + 'force_language': 'bool', + 'emailed': 'bool', + 'verify_phone_number': 'str', + 'verify_bank_account': 'str', + 'declined': 'bool', + 'declined_on': 'datetime', + 'forwarded': 'str', + 'forwarded_on': 'datetime', + 'forwarded_to_email': 'str', + 'forwarded_reason': 'str', + 'message': 'str', + 'embed_url_user_id': 'str', + 'inputs': 'list[SignerInputs]', + 'embed_url': 'str', + 'attachments': 'list[SignerAttachment]', + 'redirect_url': 'str', + 'after_document': 'str', + 'integrations': 'list[InlineDocumentSignerIntegrationData]' + } + + attribute_map = { + 'email': 'email', + 'display_name': 'display_name', + 'first_name': 'first_name', + 'last_name': 'last_name', + 'email_viewed': 'email_viewed', + 'viewed': 'viewed', + 'signed': 'signed', + 'downloaded': 'downloaded', + 'signed_on': 'signed_on', + 'needs_to_sign': 'needs_to_sign', + 'approve_only': 'approve_only', + 'notify_only': 'notify_only', + 'in_person': 'in_person', + 'order': 'order', + 'language': 'language', + 'force_language': 'force_language', + 'emailed': 'emailed', + 'verify_phone_number': 'verify_phone_number', + 'verify_bank_account': 'verify_bank_account', + 'declined': 'declined', + 'declined_on': 'declined_on', + 'forwarded': 'forwarded', + 'forwarded_on': 'forwarded_on', + 'forwarded_to_email': 'forwarded_to_email', + 'forwarded_reason': 'forwarded_reason', + 'message': 'message', + 'embed_url_user_id': 'embed_url_user_id', + 'inputs': 'inputs', + 'embed_url': 'embed_url', + 'attachments': 'attachments', + 'redirect_url': 'redirect_url', + 'after_document': 'after_document', + 'integrations': 'integrations' + } + + def __init__(self, email=None, display_name=None, first_name=None, last_name=None, email_viewed=None, viewed=None, signed=None, downloaded=None, signed_on=None, needs_to_sign=True, approve_only=None, notify_only=None, in_person=None, order=None, language=None, force_language=None, emailed=None, verify_phone_number=None, verify_bank_account=None, declined=None, declined_on=None, forwarded=None, forwarded_on=None, forwarded_to_email=None, forwarded_reason=None, message=None, embed_url_user_id=None, inputs=None, embed_url=None, attachments=None, redirect_url=None, after_document=None, integrations=None): # noqa: E501 + """Signer - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._display_name = None + self._first_name = None + self._last_name = None + self._email_viewed = None + self._viewed = None + self._signed = None + self._downloaded = None + self._signed_on = None + self._needs_to_sign = None + self._approve_only = None + self._notify_only = None + self._in_person = None + self._order = None + self._language = None + self._force_language = None + self._emailed = None + self._verify_phone_number = None + self._verify_bank_account = None + self._declined = None + self._declined_on = None + self._forwarded = None + self._forwarded_on = None + self._forwarded_to_email = None + self._forwarded_reason = None + self._message = None + self._embed_url_user_id = None + self._inputs = None + self._embed_url = None + self._attachments = None + self._redirect_url = None + self._after_document = None + self._integrations = None + self.discriminator = None + + self.email = email + if display_name is not None: + self.display_name = display_name + if first_name is not None: + self.first_name = first_name + if last_name is not None: + self.last_name = last_name + if email_viewed is not None: + self.email_viewed = email_viewed + if viewed is not None: + self.viewed = viewed + if signed is not None: + self.signed = signed + if downloaded is not None: + self.downloaded = downloaded + if signed_on is not None: + self.signed_on = signed_on + if needs_to_sign is not None: + self.needs_to_sign = needs_to_sign + if approve_only is not None: + self.approve_only = approve_only + if notify_only is not None: + self.notify_only = notify_only + if in_person is not None: + self.in_person = in_person + if order is not None: + self.order = order + if language is not None: + self.language = language + if force_language is not None: + self.force_language = force_language + if emailed is not None: + self.emailed = emailed + if verify_phone_number is not None: + self.verify_phone_number = verify_phone_number + if verify_bank_account is not None: + self.verify_bank_account = verify_bank_account + if declined is not None: + self.declined = declined + if declined_on is not None: + self.declined_on = declined_on + if forwarded is not None: + self.forwarded = forwarded + if forwarded_on is not None: + self.forwarded_on = forwarded_on + if forwarded_to_email is not None: + self.forwarded_to_email = forwarded_to_email + if forwarded_reason is not None: + self.forwarded_reason = forwarded_reason + if message is not None: + self.message = message + if embed_url_user_id is not None: + self.embed_url_user_id = embed_url_user_id + if inputs is not None: + self.inputs = inputs + if embed_url is not None: + self.embed_url = embed_url + if attachments is not None: + self.attachments = attachments + if redirect_url is not None: + self.redirect_url = redirect_url + if after_document is not None: + self.after_document = after_document + if integrations is not None: + self.integrations = integrations + + @property + def email(self): + """Gets the email of this Signer. # noqa: E501 + + + :return: The email of this Signer. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this Signer. + + + :param email: The email of this Signer. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) > 255: + raise ValueError("Invalid value for `email`, length must be less than or equal to `255`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def display_name(self): + """Gets the display_name of this Signer. # noqa: E501 + + + :return: The display_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._display_name + + @display_name.setter + def display_name(self, display_name): + """Sets the display_name of this Signer. + + + :param display_name: The display_name of this Signer. # noqa: E501 + :type: str + """ + if display_name is not None and len(display_name) < 1: + raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 + + self._display_name = display_name + + @property + def first_name(self): + """Gets the first_name of this Signer. # noqa: E501 + + + :return: The first_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._first_name + + @first_name.setter + def first_name(self, first_name): + """Sets the first_name of this Signer. + + + :param first_name: The first_name of this Signer. # noqa: E501 + :type: str + """ + if first_name is not None and len(first_name) > 255: + raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 + + self._first_name = first_name + + @property + def last_name(self): + """Gets the last_name of this Signer. # noqa: E501 + + + :return: The last_name of this Signer. # noqa: E501 + :rtype: str + """ + return self._last_name + + @last_name.setter + def last_name(self, last_name): + """Sets the last_name of this Signer. + + + :param last_name: The last_name of this Signer. # noqa: E501 + :type: str + """ + if last_name is not None and len(last_name) > 255: + raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 + + self._last_name = last_name + + @property + def email_viewed(self): + """Gets the email_viewed of this Signer. # noqa: E501 + + + :return: The email_viewed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._email_viewed + + @email_viewed.setter + def email_viewed(self, email_viewed): + """Sets the email_viewed of this Signer. + + + :param email_viewed: The email_viewed of this Signer. # noqa: E501 + :type: bool + """ + + self._email_viewed = email_viewed + + @property + def viewed(self): + """Gets the viewed of this Signer. # noqa: E501 + + + :return: The viewed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._viewed + + @viewed.setter + def viewed(self, viewed): + """Sets the viewed of this Signer. + + + :param viewed: The viewed of this Signer. # noqa: E501 + :type: bool + """ + + self._viewed = viewed + + @property + def signed(self): + """Gets the signed of this Signer. # noqa: E501 + + + :return: The signed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._signed + + @signed.setter + def signed(self, signed): + """Sets the signed of this Signer. + + + :param signed: The signed of this Signer. # noqa: E501 + :type: bool + """ + + self._signed = signed + + @property + def downloaded(self): + """Gets the downloaded of this Signer. # noqa: E501 + + + :return: The downloaded of this Signer. # noqa: E501 + :rtype: bool + """ + return self._downloaded + + @downloaded.setter + def downloaded(self, downloaded): + """Sets the downloaded of this Signer. + + + :param downloaded: The downloaded of this Signer. # noqa: E501 + :type: bool + """ + + self._downloaded = downloaded + + @property + def signed_on(self): + """Gets the signed_on of this Signer. # noqa: E501 + + + :return: The signed_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._signed_on + + @signed_on.setter + def signed_on(self, signed_on): + """Sets the signed_on of this Signer. + + + :param signed_on: The signed_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._signed_on = signed_on + + @property + def needs_to_sign(self): + """Gets the needs_to_sign of this Signer. # noqa: E501 + + + :return: The needs_to_sign of this Signer. # noqa: E501 + :rtype: bool + """ + return self._needs_to_sign + + @needs_to_sign.setter + def needs_to_sign(self, needs_to_sign): + """Sets the needs_to_sign of this Signer. + + + :param needs_to_sign: The needs_to_sign of this Signer. # noqa: E501 + :type: bool + """ + + self._needs_to_sign = needs_to_sign + + @property + def approve_only(self): + """Gets the approve_only of this Signer. # noqa: E501 + + + :return: The approve_only of this Signer. # noqa: E501 + :rtype: bool + """ + return self._approve_only + + @approve_only.setter + def approve_only(self, approve_only): + """Sets the approve_only of this Signer. + + + :param approve_only: The approve_only of this Signer. # noqa: E501 + :type: bool + """ + + self._approve_only = approve_only + + @property + def notify_only(self): + """Gets the notify_only of this Signer. # noqa: E501 + + + :return: The notify_only of this Signer. # noqa: E501 + :rtype: bool + """ + return self._notify_only + + @notify_only.setter + def notify_only(self, notify_only): + """Sets the notify_only of this Signer. + + + :param notify_only: The notify_only of this Signer. # noqa: E501 + :type: bool + """ + + self._notify_only = notify_only + + @property + def in_person(self): + """Gets the in_person of this Signer. # noqa: E501 + + + :return: The in_person of this Signer. # noqa: E501 + :rtype: bool + """ + return self._in_person + + @in_person.setter + def in_person(self, in_person): + """Sets the in_person of this Signer. + + + :param in_person: The in_person of this Signer. # noqa: E501 + :type: bool + """ + + self._in_person = in_person + + @property + def order(self): + """Gets the order of this Signer. # noqa: E501 + + + :return: The order of this Signer. # noqa: E501 + :rtype: int + """ + return self._order + + @order.setter + def order(self, order): + """Sets the order of this Signer. + + + :param order: The order of this Signer. # noqa: E501 + :type: int + """ + if order is not None and order > 2147483647: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 + if order is not None and order < 0: # noqa: E501 + raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 + + self._order = order + + @property + def language(self): + """Gets the language of this Signer. # noqa: E501 + + + :return: The language of this Signer. # noqa: E501 + :rtype: str + """ + return self._language + + @language.setter + def language(self, language): + """Sets the language of this Signer. + + + :param language: The language of this Signer. # noqa: E501 + :type: str + """ + allowed_values = ["en", "en-gb", "nl", "fr", "de", "he", "da", "fi", "hu", "it", "no", "pl", "pt", "es", "sv", "ru"] # noqa: E501 + if language not in allowed_values: + raise ValueError( + "Invalid value for `language` ({0}), must be one of {1}" # noqa: E501 + .format(language, allowed_values) + ) + + self._language = language + + @property + def force_language(self): + """Gets the force_language of this Signer. # noqa: E501 + + + :return: The force_language of this Signer. # noqa: E501 + :rtype: bool + """ + return self._force_language + + @force_language.setter + def force_language(self, force_language): + """Sets the force_language of this Signer. + + + :param force_language: The force_language of this Signer. # noqa: E501 + :type: bool + """ + + self._force_language = force_language + + @property + def emailed(self): + """Gets the emailed of this Signer. # noqa: E501 + + + :return: The emailed of this Signer. # noqa: E501 + :rtype: bool + """ + return self._emailed + + @emailed.setter + def emailed(self, emailed): + """Sets the emailed of this Signer. + + + :param emailed: The emailed of this Signer. # noqa: E501 + :type: bool + """ + + self._emailed = emailed + + @property + def verify_phone_number(self): + """Gets the verify_phone_number of this Signer. # noqa: E501 + + + :return: The verify_phone_number of this Signer. # noqa: E501 + :rtype: str + """ + return self._verify_phone_number + + @verify_phone_number.setter + def verify_phone_number(self, verify_phone_number): + """Sets the verify_phone_number of this Signer. + + + :param verify_phone_number: The verify_phone_number of this Signer. # noqa: E501 + :type: str + """ + if verify_phone_number is not None and len(verify_phone_number) > 255: + raise ValueError("Invalid value for `verify_phone_number`, length must be less than or equal to `255`") # noqa: E501 + + self._verify_phone_number = verify_phone_number + + @property + def verify_bank_account(self): + """Gets the verify_bank_account of this Signer. # noqa: E501 + + + :return: The verify_bank_account of this Signer. # noqa: E501 + :rtype: str + """ + return self._verify_bank_account + + @verify_bank_account.setter + def verify_bank_account(self, verify_bank_account): + """Sets the verify_bank_account of this Signer. + + + :param verify_bank_account: The verify_bank_account of this Signer. # noqa: E501 + :type: str + """ + if verify_bank_account is not None and len(verify_bank_account) > 255: + raise ValueError("Invalid value for `verify_bank_account`, length must be less than or equal to `255`") # noqa: E501 + + self._verify_bank_account = verify_bank_account + + @property + def declined(self): + """Gets the declined of this Signer. # noqa: E501 + + + :return: The declined of this Signer. # noqa: E501 + :rtype: bool + """ + return self._declined + + @declined.setter + def declined(self, declined): + """Sets the declined of this Signer. + + + :param declined: The declined of this Signer. # noqa: E501 + :type: bool + """ + + self._declined = declined + + @property + def declined_on(self): + """Gets the declined_on of this Signer. # noqa: E501 + + + :return: The declined_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._declined_on + + @declined_on.setter + def declined_on(self, declined_on): + """Sets the declined_on of this Signer. + + + :param declined_on: The declined_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._declined_on = declined_on + + @property + def forwarded(self): + """Gets the forwarded of this Signer. # noqa: E501 + + + :return: The forwarded of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded + + @forwarded.setter + def forwarded(self, forwarded): + """Sets the forwarded of this Signer. + + + :param forwarded: The forwarded of this Signer. # noqa: E501 + :type: str + """ + + self._forwarded = forwarded + + @property + def forwarded_on(self): + """Gets the forwarded_on of this Signer. # noqa: E501 + + + :return: The forwarded_on of this Signer. # noqa: E501 + :rtype: datetime + """ + return self._forwarded_on + + @forwarded_on.setter + def forwarded_on(self, forwarded_on): + """Sets the forwarded_on of this Signer. + + + :param forwarded_on: The forwarded_on of this Signer. # noqa: E501 + :type: datetime + """ + + self._forwarded_on = forwarded_on + + @property + def forwarded_to_email(self): + """Gets the forwarded_to_email of this Signer. # noqa: E501 + + + :return: The forwarded_to_email of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded_to_email + + @forwarded_to_email.setter + def forwarded_to_email(self, forwarded_to_email): + """Sets the forwarded_to_email of this Signer. + + + :param forwarded_to_email: The forwarded_to_email of this Signer. # noqa: E501 + :type: str + """ + if forwarded_to_email is not None and len(forwarded_to_email) < 1: + raise ValueError("Invalid value for `forwarded_to_email`, length must be greater than or equal to `1`") # noqa: E501 + + self._forwarded_to_email = forwarded_to_email + + @property + def forwarded_reason(self): + """Gets the forwarded_reason of this Signer. # noqa: E501 + + + :return: The forwarded_reason of this Signer. # noqa: E501 + :rtype: str + """ + return self._forwarded_reason + + @forwarded_reason.setter + def forwarded_reason(self, forwarded_reason): + """Sets the forwarded_reason of this Signer. + + + :param forwarded_reason: The forwarded_reason of this Signer. # noqa: E501 + :type: str + """ + if forwarded_reason is not None and len(forwarded_reason) < 1: + raise ValueError("Invalid value for `forwarded_reason`, length must be greater than or equal to `1`") # noqa: E501 + + self._forwarded_reason = forwarded_reason + + @property + def message(self): + """Gets the message of this Signer. # noqa: E501 + + + :return: The message of this Signer. # noqa: E501 + :rtype: str + """ + return self._message + + @message.setter + def message(self, message): + """Sets the message of this Signer. + + + :param message: The message of this Signer. # noqa: E501 + :type: str + """ + if message is not None and len(message) < 1: + raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 + + self._message = message + + @property + def embed_url_user_id(self): + """Gets the embed_url_user_id of this Signer. # noqa: E501 + + + :return: The embed_url_user_id of this Signer. # noqa: E501 + :rtype: str + """ + return self._embed_url_user_id + + @embed_url_user_id.setter + def embed_url_user_id(self, embed_url_user_id): + """Sets the embed_url_user_id of this Signer. + + + :param embed_url_user_id: The embed_url_user_id of this Signer. # noqa: E501 + :type: str + """ + if embed_url_user_id is not None and len(embed_url_user_id) > 255: + raise ValueError("Invalid value for `embed_url_user_id`, length must be less than or equal to `255`") # noqa: E501 + + self._embed_url_user_id = embed_url_user_id + + @property + def inputs(self): + """Gets the inputs of this Signer. # noqa: E501 + + + :return: The inputs of this Signer. # noqa: E501 + :rtype: list[SignerInputs] + """ + return self._inputs + + @inputs.setter + def inputs(self, inputs): + """Sets the inputs of this Signer. + + + :param inputs: The inputs of this Signer. # noqa: E501 + :type: list[SignerInputs] + """ + + self._inputs = inputs + + @property + def embed_url(self): + """Gets the embed_url of this Signer. # noqa: E501 + + + :return: The embed_url of this Signer. # noqa: E501 + :rtype: str + """ + return self._embed_url + + @embed_url.setter + def embed_url(self, embed_url): + """Sets the embed_url of this Signer. + + + :param embed_url: The embed_url of this Signer. # noqa: E501 + :type: str + """ + if embed_url is not None and len(embed_url) < 1: + raise ValueError("Invalid value for `embed_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._embed_url = embed_url + + @property + def attachments(self): + """Gets the attachments of this Signer. # noqa: E501 + + + :return: The attachments of this Signer. # noqa: E501 + :rtype: list[SignerAttachment] + """ + return self._attachments + + @attachments.setter + def attachments(self, attachments): + """Sets the attachments of this Signer. + + + :param attachments: The attachments of this Signer. # noqa: E501 + :type: list[SignerAttachment] + """ + + self._attachments = attachments + + @property + def redirect_url(self): + """Gets the redirect_url of this Signer. # noqa: E501 + + + :return: The redirect_url of this Signer. # noqa: E501 + :rtype: str + """ + return self._redirect_url + + @redirect_url.setter + def redirect_url(self, redirect_url): + """Sets the redirect_url of this Signer. + + + :param redirect_url: The redirect_url of this Signer. # noqa: E501 + :type: str + """ + if redirect_url is not None and len(redirect_url) > 2100: + raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._redirect_url = redirect_url + + @property + def after_document(self): + """Gets the after_document of this Signer. # noqa: E501 + + + :return: The after_document of this Signer. # noqa: E501 + :rtype: str + """ + return self._after_document + + @after_document.setter + def after_document(self, after_document): + """Sets the after_document of this Signer. + + + :param after_document: The after_document of this Signer. # noqa: E501 + :type: str + """ + + self._after_document = after_document + + @property + def integrations(self): + """Gets the integrations of this Signer. # noqa: E501 + + + :return: The integrations of this Signer. # noqa: E501 + :rtype: list[InlineDocumentSignerIntegrationData] + """ + return self._integrations + + @integrations.setter + def integrations(self, integrations): + """Sets the integrations of this Signer. + + + :param integrations: The integrations of this Signer. # noqa: E501 + :type: list[InlineDocumentSignerIntegrationData] + """ + + self._integrations = integrations + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Signer): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/signer_attachment.py b/signrequest_client/models/signer_attachment.py new file mode 100644 index 0000000..a991a13 --- /dev/null +++ b/signrequest_client/models/signer_attachment.py @@ -0,0 +1,198 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 + + +class SignerAttachment(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'name': 'str', + 'file': 'str', + 'for_attachment': 'RequiredAttachment' + } + + attribute_map = { + 'uuid': 'uuid', + 'name': 'name', + 'file': 'file', + 'for_attachment': 'for_attachment' + } + + def __init__(self, uuid=None, name=None, file=None, for_attachment=None): # noqa: E501 + """SignerAttachment - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._name = None + self._file = None + self._for_attachment = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + if file is not None: + self.file = file + if for_attachment is not None: + self.for_attachment = for_attachment + + @property + def uuid(self): + """Gets the uuid of this SignerAttachment. # noqa: E501 + + + :return: The uuid of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this SignerAttachment. + + + :param uuid: The uuid of this SignerAttachment. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this SignerAttachment. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this SignerAttachment. + + Defaults to filename # noqa: E501 + + :param name: The name of this SignerAttachment. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def file(self): + """Gets the file of this SignerAttachment. # noqa: E501 + + + :return: The file of this SignerAttachment. # noqa: E501 + :rtype: str + """ + return self._file + + @file.setter + def file(self, file): + """Sets the file of this SignerAttachment. + + + :param file: The file of this SignerAttachment. # noqa: E501 + :type: str + """ + + self._file = file + + @property + def for_attachment(self): + """Gets the for_attachment of this SignerAttachment. # noqa: E501 + + + :return: The for_attachment of this SignerAttachment. # noqa: E501 + :rtype: RequiredAttachment + """ + return self._for_attachment + + @for_attachment.setter + def for_attachment(self, for_attachment): + """Sets the for_attachment of this SignerAttachment. + + + :param for_attachment: The for_attachment of this SignerAttachment. # noqa: E501 + :type: RequiredAttachment + """ + + self._for_attachment = for_attachment + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignerAttachment): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/signer_inputs.py b/signrequest_client/models/signer_inputs.py new file mode 100644 index 0000000..41f14f0 --- /dev/null +++ b/signrequest_client/models/signer_inputs.py @@ -0,0 +1,279 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class SignerInputs(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'type': 'str', + 'page_index': 'int', + 'text': 'str', + 'checkbox_value': 'bool', + 'date_value': 'date', + 'external_id': 'str', + 'placeholder_uuid': 'str' + } + + attribute_map = { + 'type': 'type', + 'page_index': 'page_index', + 'text': 'text', + 'checkbox_value': 'checkbox_value', + 'date_value': 'date_value', + 'external_id': 'external_id', + 'placeholder_uuid': 'placeholder_uuid' + } + + def __init__(self, type=None, page_index=None, text=None, checkbox_value=None, date_value=None, external_id=None, placeholder_uuid=None): # noqa: E501 + """SignerInputs - a model defined in Swagger""" # noqa: E501 + + self._type = None + self._page_index = None + self._text = None + self._checkbox_value = None + self._date_value = None + self._external_id = None + self._placeholder_uuid = None + self.discriminator = None + + if type is not None: + self.type = type + self.page_index = page_index + if text is not None: + self.text = text + if checkbox_value is not None: + self.checkbox_value = checkbox_value + if date_value is not None: + self.date_value = date_value + if external_id is not None: + self.external_id = external_id + if placeholder_uuid is not None: + self.placeholder_uuid = placeholder_uuid + + @property + def type(self): + """Gets the type of this SignerInputs. # noqa: E501 + + + :return: The type of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._type + + @type.setter + def type(self, type): + """Sets the type of this SignerInputs. + + + :param type: The type of this SignerInputs. # noqa: E501 + :type: str + """ + allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 + if type not in allowed_values: + raise ValueError( + "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 + .format(type, allowed_values) + ) + + self._type = type + + @property + def page_index(self): + """Gets the page_index of this SignerInputs. # noqa: E501 + + + :return: The page_index of this SignerInputs. # noqa: E501 + :rtype: int + """ + return self._page_index + + @page_index.setter + def page_index(self, page_index): + """Sets the page_index of this SignerInputs. + + + :param page_index: The page_index of this SignerInputs. # noqa: E501 + :type: int + """ + if page_index is None: + raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 + + self._page_index = page_index + + @property + def text(self): + """Gets the text of this SignerInputs. # noqa: E501 + + + :return: The text of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._text + + @text.setter + def text(self, text): + """Sets the text of this SignerInputs. + + + :param text: The text of this SignerInputs. # noqa: E501 + :type: str + """ + + self._text = text + + @property + def checkbox_value(self): + """Gets the checkbox_value of this SignerInputs. # noqa: E501 + + + :return: The checkbox_value of this SignerInputs. # noqa: E501 + :rtype: bool + """ + return self._checkbox_value + + @checkbox_value.setter + def checkbox_value(self, checkbox_value): + """Sets the checkbox_value of this SignerInputs. + + + :param checkbox_value: The checkbox_value of this SignerInputs. # noqa: E501 + :type: bool + """ + + self._checkbox_value = checkbox_value + + @property + def date_value(self): + """Gets the date_value of this SignerInputs. # noqa: E501 + + + :return: The date_value of this SignerInputs. # noqa: E501 + :rtype: date + """ + return self._date_value + + @date_value.setter + def date_value(self, date_value): + """Sets the date_value of this SignerInputs. + + + :param date_value: The date_value of this SignerInputs. # noqa: E501 + :type: date + """ + + self._date_value = date_value + + @property + def external_id(self): + """Gets the external_id of this SignerInputs. # noqa: E501 + + + :return: The external_id of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._external_id + + @external_id.setter + def external_id(self, external_id): + """Sets the external_id of this SignerInputs. + + + :param external_id: The external_id of this SignerInputs. # noqa: E501 + :type: str + """ + if external_id is not None and len(external_id) > 255: + raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 + + self._external_id = external_id + + @property + def placeholder_uuid(self): + """Gets the placeholder_uuid of this SignerInputs. # noqa: E501 + + + :return: The placeholder_uuid of this SignerInputs. # noqa: E501 + :rtype: str + """ + return self._placeholder_uuid + + @placeholder_uuid.setter + def placeholder_uuid(self, placeholder_uuid): + """Sets the placeholder_uuid of this SignerInputs. + + + :param placeholder_uuid: The placeholder_uuid of this SignerInputs. # noqa: E501 + :type: str + """ + if placeholder_uuid is not None and len(placeholder_uuid) > 36: + raise ValueError("Invalid value for `placeholder_uuid`, length must be less than or equal to `36`") # noqa: E501 + + self._placeholder_uuid = placeholder_uuid + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SignerInputs): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/signing_log.py b/signrequest_client/models/signing_log.py new file mode 100644 index 0000000..3490f17 --- /dev/null +++ b/signrequest_client/models/signing_log.py @@ -0,0 +1,144 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class SigningLog(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'pdf': 'str', + 'security_hash': 'str' + } + + attribute_map = { + 'pdf': 'pdf', + 'security_hash': 'security_hash' + } + + def __init__(self, pdf=None, security_hash=None): # noqa: E501 + """SigningLog - a model defined in Swagger""" # noqa: E501 + + self._pdf = None + self._security_hash = None + self.discriminator = None + + if pdf is not None: + self.pdf = pdf + if security_hash is not None: + self.security_hash = security_hash + + @property + def pdf(self): + """Gets the pdf of this SigningLog. # noqa: E501 + + Temporary URL to signing log, expires in five minutes # noqa: E501 + + :return: The pdf of this SigningLog. # noqa: E501 + :rtype: str + """ + return self._pdf + + @pdf.setter + def pdf(self, pdf): + """Sets the pdf of this SigningLog. + + Temporary URL to signing log, expires in five minutes # noqa: E501 + + :param pdf: The pdf of this SigningLog. # noqa: E501 + :type: str + """ + + self._pdf = pdf + + @property + def security_hash(self): + """Gets the security_hash of this SigningLog. # noqa: E501 + + SHA256 hash of PDF contents # noqa: E501 + + :return: The security_hash of this SigningLog. # noqa: E501 + :rtype: str + """ + return self._security_hash + + @security_hash.setter + def security_hash(self, security_hash): + """Sets the security_hash of this SigningLog. + + SHA256 hash of PDF contents # noqa: E501 + + :param security_hash: The security_hash of this SigningLog. # noqa: E501 + :type: str + """ + if security_hash is not None and len(security_hash) < 1: + raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 + + self._security_hash = security_hash + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, SigningLog): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/team.py b/signrequest_client/models/team.py new file mode 100644 index 0000000..a029e10 --- /dev/null +++ b/signrequest_client/models/team.py @@ -0,0 +1,312 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.inline_team_member import InlineTeamMember # noqa: F401,E501 + + +class Team(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'name': 'str', + 'subdomain': 'str', + 'url': 'str', + 'logo': 'str', + 'phone': 'str', + 'primary_color': 'str', + 'events_callback_url': 'str', + 'members': 'list[InlineTeamMember]' + } + + attribute_map = { + 'name': 'name', + 'subdomain': 'subdomain', + 'url': 'url', + 'logo': 'logo', + 'phone': 'phone', + 'primary_color': 'primary_color', + 'events_callback_url': 'events_callback_url', + 'members': 'members' + } + + def __init__(self, name=None, subdomain=None, url=None, logo=None, phone=None, primary_color=None, events_callback_url=None, members=None): # noqa: E501 + """Team - a model defined in Swagger""" # noqa: E501 + + self._name = None + self._subdomain = None + self._url = None + self._logo = None + self._phone = None + self._primary_color = None + self._events_callback_url = None + self._members = None + self.discriminator = None + + self.name = name + self.subdomain = subdomain + if url is not None: + self.url = url + if logo is not None: + self.logo = logo + if phone is not None: + self.phone = phone + if primary_color is not None: + self.primary_color = primary_color + if events_callback_url is not None: + self.events_callback_url = events_callback_url + if members is not None: + self.members = members + + @property + def name(self): + """Gets the name of this Team. # noqa: E501 + + + :return: The name of this Team. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Team. + + + :param name: The name of this Team. # noqa: E501 + :type: str + """ + if name is None: + raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 + if name is not None and len(name) > 100: + raise ValueError("Invalid value for `name`, length must be less than or equal to `100`") # noqa: E501 + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def subdomain(self): + """Gets the subdomain of this Team. # noqa: E501 + + + :return: The subdomain of this Team. # noqa: E501 + :rtype: str + """ + return self._subdomain + + @subdomain.setter + def subdomain(self, subdomain): + """Sets the subdomain of this Team. + + + :param subdomain: The subdomain of this Team. # noqa: E501 + :type: str + """ + if subdomain is None: + raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 + if subdomain is not None and len(subdomain) > 100: + raise ValueError("Invalid value for `subdomain`, length must be less than or equal to `100`") # noqa: E501 + if subdomain is not None and len(subdomain) < 1: + raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 + + self._subdomain = subdomain + + @property + def url(self): + """Gets the url of this Team. # noqa: E501 + + + :return: The url of this Team. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Team. + + + :param url: The url of this Team. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def logo(self): + """Gets the logo of this Team. # noqa: E501 + + + :return: The logo of this Team. # noqa: E501 + :rtype: str + """ + return self._logo + + @logo.setter + def logo(self, logo): + """Sets the logo of this Team. + + + :param logo: The logo of this Team. # noqa: E501 + :type: str + """ + + self._logo = logo + + @property + def phone(self): + """Gets the phone of this Team. # noqa: E501 + + + :return: The phone of this Team. # noqa: E501 + :rtype: str + """ + return self._phone + + @phone.setter + def phone(self, phone): + """Sets the phone of this Team. + + + :param phone: The phone of this Team. # noqa: E501 + :type: str + """ + if phone is not None and len(phone) > 100: + raise ValueError("Invalid value for `phone`, length must be less than or equal to `100`") # noqa: E501 + + self._phone = phone + + @property + def primary_color(self): + """Gets the primary_color of this Team. # noqa: E501 + + + :return: The primary_color of this Team. # noqa: E501 + :rtype: str + """ + return self._primary_color + + @primary_color.setter + def primary_color(self, primary_color): + """Sets the primary_color of this Team. + + + :param primary_color: The primary_color of this Team. # noqa: E501 + :type: str + """ + if primary_color is not None and len(primary_color) > 100: + raise ValueError("Invalid value for `primary_color`, length must be less than or equal to `100`") # noqa: E501 + + self._primary_color = primary_color + + @property + def events_callback_url(self): + """Gets the events_callback_url of this Team. # noqa: E501 + + + :return: The events_callback_url of this Team. # noqa: E501 + :rtype: str + """ + return self._events_callback_url + + @events_callback_url.setter + def events_callback_url(self, events_callback_url): + """Sets the events_callback_url of this Team. + + + :param events_callback_url: The events_callback_url of this Team. # noqa: E501 + :type: str + """ + if events_callback_url is not None and len(events_callback_url) > 2100: + raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 + + self._events_callback_url = events_callback_url + + @property + def members(self): + """Gets the members of this Team. # noqa: E501 + + + :return: The members of this Team. # noqa: E501 + :rtype: list[InlineTeamMember] + """ + return self._members + + @members.setter + def members(self, members): + """Sets the members of this Team. + + + :param members: The members of this Team. # noqa: E501 + :type: list[InlineTeamMember] + """ + + self._members = members + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Team): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/team_member.py b/signrequest_client/models/team_member.py new file mode 100644 index 0000000..ceeb4c8 --- /dev/null +++ b/signrequest_client/models/team_member.py @@ -0,0 +1,246 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.user import User # noqa: F401,E501 + + +class TeamMember(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'uuid': 'str', + 'url': 'str', + 'user': 'User', + 'is_admin': 'bool', + 'is_active': 'bool', + 'is_owner': 'bool' + } + + attribute_map = { + 'uuid': 'uuid', + 'url': 'url', + 'user': 'user', + 'is_admin': 'is_admin', + 'is_active': 'is_active', + 'is_owner': 'is_owner' + } + + def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 + """TeamMember - a model defined in Swagger""" # noqa: E501 + + self._uuid = None + self._url = None + self._user = None + self._is_admin = None + self._is_active = None + self._is_owner = None + self.discriminator = None + + if uuid is not None: + self.uuid = uuid + if url is not None: + self.url = url + if user is not None: + self.user = user + if is_admin is not None: + self.is_admin = is_admin + if is_active is not None: + self.is_active = is_active + if is_owner is not None: + self.is_owner = is_owner + + @property + def uuid(self): + """Gets the uuid of this TeamMember. # noqa: E501 + + + :return: The uuid of this TeamMember. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this TeamMember. + + + :param uuid: The uuid of this TeamMember. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def url(self): + """Gets the url of this TeamMember. # noqa: E501 + + + :return: The url of this TeamMember. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this TeamMember. + + + :param url: The url of this TeamMember. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def user(self): + """Gets the user of this TeamMember. # noqa: E501 + + + :return: The user of this TeamMember. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this TeamMember. + + + :param user: The user of this TeamMember. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def is_admin(self): + """Gets the is_admin of this TeamMember. # noqa: E501 + + + :return: The is_admin of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_admin + + @is_admin.setter + def is_admin(self, is_admin): + """Sets the is_admin of this TeamMember. + + + :param is_admin: The is_admin of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_admin = is_admin + + @property + def is_active(self): + """Gets the is_active of this TeamMember. # noqa: E501 + + + :return: The is_active of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_active + + @is_active.setter + def is_active(self, is_active): + """Sets the is_active of this TeamMember. + + + :param is_active: The is_active of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_active = is_active + + @property + def is_owner(self): + """Gets the is_owner of this TeamMember. # noqa: E501 + + + :return: The is_owner of this TeamMember. # noqa: E501 + :rtype: bool + """ + return self._is_owner + + @is_owner.setter + def is_owner(self, is_owner): + """Sets the is_owner of this TeamMember. + + + :param is_owner: The is_owner of this TeamMember. # noqa: E501 + :type: bool + """ + + self._is_owner = is_owner + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, TeamMember): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/template.py b/signrequest_client/models/template.py new file mode 100644 index 0000000..7ddf311 --- /dev/null +++ b/signrequest_client/models/template.py @@ -0,0 +1,259 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + +from signrequest_client.models.document_signer_template_conf import DocumentSignerTemplateConf # noqa: F401,E501 +from signrequest_client.models.user import User # noqa: F401,E501 + + +class Template(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'name': 'str', + 'uuid': 'str', + 'user': 'User', + 'who': 'str', + 'signers': 'list[DocumentSignerTemplateConf]' + } + + attribute_map = { + 'url': 'url', + 'name': 'name', + 'uuid': 'uuid', + 'user': 'user', + 'who': 'who', + 'signers': 'signers' + } + + def __init__(self, url=None, name=None, uuid=None, user=None, who=None, signers=None): # noqa: E501 + """Template - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._name = None + self._uuid = None + self._user = None + self._who = None + self._signers = None + self.discriminator = None + + if url is not None: + self.url = url + if name is not None: + self.name = name + if uuid is not None: + self.uuid = uuid + if user is not None: + self.user = user + if who is not None: + self.who = who + if signers is not None: + self.signers = signers + + @property + def url(self): + """Gets the url of this Template. # noqa: E501 + + + :return: The url of this Template. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this Template. + + + :param url: The url of this Template. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def name(self): + """Gets the name of this Template. # noqa: E501 + + Defaults to filename # noqa: E501 + + :return: The name of this Template. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this Template. + + Defaults to filename # noqa: E501 + + :param name: The name of this Template. # noqa: E501 + :type: str + """ + if name is not None and len(name) < 1: + raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 + + self._name = name + + @property + def uuid(self): + """Gets the uuid of this Template. # noqa: E501 + + + :return: The uuid of this Template. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this Template. + + + :param uuid: The uuid of this Template. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def user(self): + """Gets the user of this Template. # noqa: E501 + + + :return: The user of this Template. # noqa: E501 + :rtype: User + """ + return self._user + + @user.setter + def user(self, user): + """Sets the user of this Template. + + + :param user: The user of this Template. # noqa: E501 + :type: User + """ + + self._user = user + + @property + def who(self): + """Gets the who of this Template. # noqa: E501 + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :return: The who of this Template. # noqa: E501 + :rtype: str + """ + return self._who + + @who.setter + def who(self, who): + """Sets the who of this Template. + + `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 + + :param who: The who of this Template. # noqa: E501 + :type: str + """ + allowed_values = ["m", "mo", "o"] # noqa: E501 + if who not in allowed_values: + raise ValueError( + "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 + .format(who, allowed_values) + ) + + self._who = who + + @property + def signers(self): + """Gets the signers of this Template. # noqa: E501 + + + :return: The signers of this Template. # noqa: E501 + :rtype: list[DocumentSignerTemplateConf] + """ + return self._signers + + @signers.setter + def signers(self, signers): + """Sets the signers of this Template. + + + :param signers: The signers of this Template. # noqa: E501 + :type: list[DocumentSignerTemplateConf] + """ + + self._signers = signers + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, Template): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/user.py b/signrequest_client/models/user.py new file mode 100644 index 0000000..953698a --- /dev/null +++ b/signrequest_client/models/user.py @@ -0,0 +1,201 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class User(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'email': 'str', + 'first_name': 'str', + 'last_name': 'str', + 'display_name': 'str' + } + + attribute_map = { + 'email': 'email', + 'first_name': 'first_name', + 'last_name': 'last_name', + 'display_name': 'display_name' + } + + def __init__(self, email=None, first_name=None, last_name=None, display_name=None): # noqa: E501 + """User - a model defined in Swagger""" # noqa: E501 + + self._email = None + self._first_name = None + self._last_name = None + self._display_name = None + self.discriminator = None + + self.email = email + if first_name is not None: + self.first_name = first_name + if last_name is not None: + self.last_name = last_name + if display_name is not None: + self.display_name = display_name + + @property + def email(self): + """Gets the email of this User. # noqa: E501 + + + :return: The email of this User. # noqa: E501 + :rtype: str + """ + return self._email + + @email.setter + def email(self, email): + """Sets the email of this User. + + + :param email: The email of this User. # noqa: E501 + :type: str + """ + if email is None: + raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 + if email is not None and len(email) > 254: + raise ValueError("Invalid value for `email`, length must be less than or equal to `254`") # noqa: E501 + if email is not None and len(email) < 1: + raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 + + self._email = email + + @property + def first_name(self): + """Gets the first_name of this User. # noqa: E501 + + + :return: The first_name of this User. # noqa: E501 + :rtype: str + """ + return self._first_name + + @first_name.setter + def first_name(self, first_name): + """Sets the first_name of this User. + + + :param first_name: The first_name of this User. # noqa: E501 + :type: str + """ + if first_name is not None and len(first_name) > 255: + raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 + + self._first_name = first_name + + @property + def last_name(self): + """Gets the last_name of this User. # noqa: E501 + + + :return: The last_name of this User. # noqa: E501 + :rtype: str + """ + return self._last_name + + @last_name.setter + def last_name(self, last_name): + """Sets the last_name of this User. + + + :param last_name: The last_name of this User. # noqa: E501 + :type: str + """ + if last_name is not None and len(last_name) > 255: + raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 + + self._last_name = last_name + + @property + def display_name(self): + """Gets the display_name of this User. # noqa: E501 + + + :return: The display_name of this User. # noqa: E501 + :rtype: str + """ + return self._display_name + + @display_name.setter + def display_name(self, display_name): + """Sets the display_name of this User. + + + :param display_name: The display_name of this User. # noqa: E501 + :type: str + """ + if display_name is not None and len(display_name) < 1: + raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 + + self._display_name = display_name + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, User): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/models/webhook_subscription.py b/signrequest_client/models/webhook_subscription.py new file mode 100644 index 0000000..e1caf50 --- /dev/null +++ b/signrequest_client/models/webhook_subscription.py @@ -0,0 +1,292 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +import pprint +import re # noqa: F401 + +import six + + +class WebhookSubscription(object): + """NOTE: This class is auto generated by the swagger code generator program. + + Do not edit the class manually. + """ + + """ + Attributes: + swagger_types (dict): The key is attribute name + and the value is attribute type. + attribute_map (dict): The key is attribute name + and the value is json key in definition. + """ + swagger_types = { + 'url': 'str', + 'uuid': 'str', + 'name': 'str', + 'event_type': 'str', + 'callback_url': 'str', + 'integration': 'str', + 'created': 'datetime' + } + + attribute_map = { + 'url': 'url', + 'uuid': 'uuid', + 'name': 'name', + 'event_type': 'event_type', + 'callback_url': 'callback_url', + 'integration': 'integration', + 'created': 'created' + } + + def __init__(self, url=None, uuid=None, name=None, event_type=None, callback_url=None, integration=None, created=None): # noqa: E501 + """WebhookSubscription - a model defined in Swagger""" # noqa: E501 + + self._url = None + self._uuid = None + self._name = None + self._event_type = None + self._callback_url = None + self._integration = None + self._created = None + self.discriminator = None + + if url is not None: + self.url = url + if uuid is not None: + self.uuid = uuid + if name is not None: + self.name = name + self.event_type = event_type + self.callback_url = callback_url + if integration is not None: + self.integration = integration + if created is not None: + self.created = created + + @property + def url(self): + """Gets the url of this WebhookSubscription. # noqa: E501 + + + :return: The url of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._url + + @url.setter + def url(self, url): + """Sets the url of this WebhookSubscription. + + + :param url: The url of this WebhookSubscription. # noqa: E501 + :type: str + """ + + self._url = url + + @property + def uuid(self): + """Gets the uuid of this WebhookSubscription. # noqa: E501 + + + :return: The uuid of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._uuid + + @uuid.setter + def uuid(self, uuid): + """Sets the uuid of this WebhookSubscription. + + + :param uuid: The uuid of this WebhookSubscription. # noqa: E501 + :type: str + """ + if uuid is not None and len(uuid) < 1: + raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 + + self._uuid = uuid + + @property + def name(self): + """Gets the name of this WebhookSubscription. # noqa: E501 + + Optional name to easily identify what webhook is used for # noqa: E501 + + :return: The name of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._name + + @name.setter + def name(self, name): + """Sets the name of this WebhookSubscription. + + Optional name to easily identify what webhook is used for # noqa: E501 + + :param name: The name of this WebhookSubscription. # noqa: E501 + :type: str + """ + if name is not None and len(name) > 255: + raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 + + self._name = name + + @property + def event_type(self): + """Gets the event_type of this WebhookSubscription. # noqa: E501 + + + :return: The event_type of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._event_type + + @event_type.setter + def event_type(self, event_type): + """Sets the event_type of this WebhookSubscription. + + + :param event_type: The event_type of this WebhookSubscription. # noqa: E501 + :type: str + """ + if event_type is None: + raise ValueError("Invalid value for `event_type`, must not be `None`") # noqa: E501 + allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 + if event_type not in allowed_values: + raise ValueError( + "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 + .format(event_type, allowed_values) + ) + + self._event_type = event_type + + @property + def callback_url(self): + """Gets the callback_url of this WebhookSubscription. # noqa: E501 + + + :return: The callback_url of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._callback_url + + @callback_url.setter + def callback_url(self, callback_url): + """Sets the callback_url of this WebhookSubscription. + + + :param callback_url: The callback_url of this WebhookSubscription. # noqa: E501 + :type: str + """ + if callback_url is None: + raise ValueError("Invalid value for `callback_url`, must not be `None`") # noqa: E501 + if callback_url is not None and len(callback_url) > 2100: + raise ValueError("Invalid value for `callback_url`, length must be less than or equal to `2100`") # noqa: E501 + if callback_url is not None and len(callback_url) < 1: + raise ValueError("Invalid value for `callback_url`, length must be greater than or equal to `1`") # noqa: E501 + + self._callback_url = callback_url + + @property + def integration(self): + """Gets the integration of this WebhookSubscription. # noqa: E501 + + + :return: The integration of this WebhookSubscription. # noqa: E501 + :rtype: str + """ + return self._integration + + @integration.setter + def integration(self, integration): + """Sets the integration of this WebhookSubscription. + + + :param integration: The integration of this WebhookSubscription. # noqa: E501 + :type: str + """ + allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 + if integration not in allowed_values: + raise ValueError( + "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 + .format(integration, allowed_values) + ) + + self._integration = integration + + @property + def created(self): + """Gets the created of this WebhookSubscription. # noqa: E501 + + + :return: The created of this WebhookSubscription. # noqa: E501 + :rtype: datetime + """ + return self._created + + @created.setter + def created(self, created): + """Sets the created of this WebhookSubscription. + + + :param created: The created of this WebhookSubscription. # noqa: E501 + :type: datetime + """ + + self._created = created + + def to_dict(self): + """Returns the model properties as a dict""" + result = {} + + for attr, _ in six.iteritems(self.swagger_types): + value = getattr(self, attr) + if isinstance(value, list): + result[attr] = list(map( + lambda x: x.to_dict() if hasattr(x, "to_dict") else x, + value + )) + elif hasattr(value, "to_dict"): + result[attr] = value.to_dict() + elif isinstance(value, dict): + result[attr] = dict(map( + lambda item: (item[0], item[1].to_dict()) + if hasattr(item[1], "to_dict") else item, + value.items() + )) + else: + result[attr] = value + + return result + + def to_str(self): + """Returns the string representation of the model""" + return pprint.pformat(self.to_dict()) + + def __repr__(self): + """For `print` and `pprint`""" + return self.to_str() + + def __eq__(self, other): + """Returns true if both objects are equal""" + if not isinstance(other, WebhookSubscription): + return False + + return self.__dict__ == other.__dict__ + + def __ne__(self, other): + """Returns true if both objects are not equal""" + return not self == other diff --git a/signrequest_client/rest.py b/signrequest_client/rest.py new file mode 100644 index 0000000..b6d5d88 --- /dev/null +++ b/signrequest_client/rest.py @@ -0,0 +1,323 @@ +# coding: utf-8 + +""" + SignRequest API + + API for SignRequest.com + + OpenAPI spec version: v1 + Contact: tech-support@signrequest.com + Generated by: https://github.com/swagger-api/swagger-codegen.git +""" + + +from __future__ import absolute_import + +import io +import json +import logging +import re +import ssl + +import certifi +# python 2 and python 3 compatibility library +import six +from six.moves.urllib.parse import urlencode + +try: + import urllib3 +except ImportError: + raise ImportError('Swagger python client requires urllib3.') + + +logger = logging.getLogger(__name__) + + +class RESTResponse(io.IOBase): + + def __init__(self, resp): + self.urllib3_response = resp + self.status = resp.status + self.reason = resp.reason + self.data = resp.data + + def getheaders(self): + """Returns a dictionary of the response headers.""" + return self.urllib3_response.getheaders() + + def getheader(self, name, default=None): + """Returns a given response header.""" + return self.urllib3_response.getheader(name, default) + + +class RESTClientObject(object): + + def __init__(self, configuration, pools_size=4, maxsize=None): + # urllib3.PoolManager will pass all kw parameters to connectionpool + # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75 # noqa: E501 + # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680 # noqa: E501 + # maxsize is the number of requests to host that are allowed in parallel # noqa: E501 + # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html # noqa: E501 + + # cert_reqs + if configuration.verify_ssl: + cert_reqs = ssl.CERT_REQUIRED + else: + cert_reqs = ssl.CERT_NONE + + # ca_certs + if configuration.ssl_ca_cert: + ca_certs = configuration.ssl_ca_cert + else: + # if not set certificate file, use Mozilla's root certificates. + ca_certs = certifi.where() + + addition_pool_args = {} + if configuration.assert_hostname is not None: + addition_pool_args['assert_hostname'] = configuration.assert_hostname # noqa: E501 + + if maxsize is None: + if configuration.connection_pool_maxsize is not None: + maxsize = configuration.connection_pool_maxsize + else: + maxsize = 4 + + # https pool manager + if configuration.proxy: + self.pool_manager = urllib3.ProxyManager( + num_pools=pools_size, + maxsize=maxsize, + cert_reqs=cert_reqs, + ca_certs=ca_certs, + cert_file=configuration.cert_file, + key_file=configuration.key_file, + proxy_url=configuration.proxy, + **addition_pool_args + ) + else: + self.pool_manager = urllib3.PoolManager( + num_pools=pools_size, + maxsize=maxsize, + cert_reqs=cert_reqs, + ca_certs=ca_certs, + cert_file=configuration.cert_file, + key_file=configuration.key_file, + **addition_pool_args + ) + + def request(self, method, url, query_params=None, headers=None, + body=None, post_params=None, _preload_content=True, + _request_timeout=None): + """Perform requests. + + :param method: http request method + :param url: http request url + :param query_params: query parameters in the url + :param headers: http request headers + :param body: request json body, for `application/json` + :param post_params: request post parameters, + `application/x-www-form-urlencoded` + and `multipart/form-data` + :param _preload_content: if False, the urllib3.HTTPResponse object will + be returned without reading/decoding response + data. Default is True. + :param _request_timeout: timeout setting for this request. If one + number provided, it will be total request + timeout. It can also be a pair (tuple) of + (connection, read) timeouts. + """ + method = method.upper() + assert method in ['GET', 'HEAD', 'DELETE', 'POST', 'PUT', + 'PATCH', 'OPTIONS'] + + if post_params and body: + raise ValueError( + "body parameter cannot be used with post_params parameter." + ) + + post_params = post_params or {} + headers = headers or {} + + timeout = None + if _request_timeout: + if isinstance(_request_timeout, (int, ) if six.PY3 else (int, long)): # noqa: E501,F821 + timeout = urllib3.Timeout(total=_request_timeout) + elif (isinstance(_request_timeout, tuple) and + len(_request_timeout) == 2): + timeout = urllib3.Timeout( + connect=_request_timeout[0], read=_request_timeout[1]) + + if 'Content-Type' not in headers: + headers['Content-Type'] = 'application/json' + + try: + # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE` + if method in ['POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE']: + if query_params: + url += '?' + urlencode(query_params) + if re.search('json', headers['Content-Type'], re.IGNORECASE): + request_body = None + if body is not None: + request_body = json.dumps(body) + r = self.pool_manager.request( + method, url, + body=request_body, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + elif headers['Content-Type'] == 'application/x-www-form-urlencoded': # noqa: E501 + r = self.pool_manager.request( + method, url, + fields=post_params, + encode_multipart=False, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + elif headers['Content-Type'] == 'multipart/form-data': + # must del headers['Content-Type'], or the correct + # Content-Type which generated by urllib3 will be + # overwritten. + del headers['Content-Type'] + r = self.pool_manager.request( + method, url, + fields=post_params, + encode_multipart=True, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + # Pass a `string` parameter directly in the body to support + # other content types than Json when `body` argument is + # provided in serialized form + elif isinstance(body, str): + request_body = body + r = self.pool_manager.request( + method, url, + body=request_body, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + else: + # Cannot generate the request from given parameters + msg = """Cannot prepare a request message for provided + arguments. Please check that your arguments match + declared content type.""" + raise ApiException(status=0, reason=msg) + # For `GET`, `HEAD` + else: + r = self.pool_manager.request(method, url, + fields=query_params, + preload_content=_preload_content, + timeout=timeout, + headers=headers) + except urllib3.exceptions.SSLError as e: + msg = "{0}\n{1}".format(type(e).__name__, str(e)) + raise ApiException(status=0, reason=msg) + + if _preload_content: + r = RESTResponse(r) + + # In the python 3, the response.data is bytes. + # we need to decode it to string. + if six.PY3: + r.data = r.data.decode('utf8') + + # log response body + logger.debug("response body: %s", r.data) + + if not 200 <= r.status <= 299: + raise ApiException(http_resp=r) + + return r + + def GET(self, url, headers=None, query_params=None, _preload_content=True, + _request_timeout=None): + return self.request("GET", url, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + query_params=query_params) + + def HEAD(self, url, headers=None, query_params=None, _preload_content=True, + _request_timeout=None): + return self.request("HEAD", url, + headers=headers, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + query_params=query_params) + + def OPTIONS(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("OPTIONS", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def DELETE(self, url, headers=None, query_params=None, body=None, + _preload_content=True, _request_timeout=None): + return self.request("DELETE", url, + headers=headers, + query_params=query_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def POST(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("POST", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def PUT(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("PUT", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + def PATCH(self, url, headers=None, query_params=None, post_params=None, + body=None, _preload_content=True, _request_timeout=None): + return self.request("PATCH", url, + headers=headers, + query_params=query_params, + post_params=post_params, + _preload_content=_preload_content, + _request_timeout=_request_timeout, + body=body) + + +class ApiException(Exception): + + def __init__(self, status=None, reason=None, http_resp=None): + if http_resp: + self.status = http_resp.status + self.reason = http_resp.reason + self.body = http_resp.data + self.headers = http_resp.getheaders() + else: + self.status = status + self.reason = reason + self.body = None + self.headers = None + + def __str__(self): + """Custom error messages for exception""" + error_message = "({0})\n"\ + "Reason: {1}\n".format(self.status, self.reason) + if self.headers: + error_message += "HTTP response headers: {0}\n".format( + self.headers) + + if self.body: + error_message += "HTTP response body: {0}\n".format(self.body) + + return error_message diff --git a/signrequest_python_client/__init__.py b/signrequest_python_client/__init__.py deleted file mode 100644 index d5f23b6..0000000 --- a/signrequest_python_client/__init__.py +++ /dev/null @@ -1,73 +0,0 @@ -# coding: utf-8 - -# flake8: noqa - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -# import apis into sdk package -from signrequest_python_client.api.api_tokens_api import ApiTokensApi -from signrequest_python_client.api.document_attachments_api import DocumentAttachmentsApi -from signrequest_python_client.api.documents_api import DocumentsApi -from signrequest_python_client.api.documents_search_api import DocumentsSearchApi -from signrequest_python_client.api.events_api import EventsApi -from signrequest_python_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi -from signrequest_python_client.api.signrequests_api import SignrequestsApi -from signrequest_python_client.api.team_members_api import TeamMembersApi -from signrequest_python_client.api.teams_api import TeamsApi -from signrequest_python_client.api.templates_api import TemplatesApi -from signrequest_python_client.api.webhooks_api import WebhooksApi - -# import ApiClient -from signrequest_python_client.api_client import ApiClient -from signrequest_python_client.configuration import Configuration -# import models into sdk package -from signrequest_python_client.models.auth_token import AuthToken -from signrequest_python_client.models.document import Document -from signrequest_python_client.models.document_attachment import DocumentAttachment -from signrequest_python_client.models.document_search import DocumentSearch -from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf -from signrequest_python_client.models.event import Event -from signrequest_python_client.models.file_from_sf import FileFromSf -from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData -from signrequest_python_client.models.inline_integration_data import InlineIntegrationData -from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags -from signrequest_python_client.models.inline_response_200 import InlineResponse200 -from signrequest_python_client.models.inline_response_200_1 import InlineResponse2001 -from signrequest_python_client.models.inline_response_200_2 import InlineResponse2002 -from signrequest_python_client.models.inline_response_200_3 import InlineResponse2003 -from signrequest_python_client.models.inline_response_200_4 import InlineResponse2004 -from signrequest_python_client.models.inline_response_200_5 import InlineResponse2005 -from signrequest_python_client.models.inline_response_200_6 import InlineResponse2006 -from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 -from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 -from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 -from signrequest_python_client.models.inline_response_201 import InlineResponse201 -from signrequest_python_client.models.inline_response_201_1 import InlineResponse2011 -from signrequest_python_client.models.inline_sign_request import InlineSignRequest -from signrequest_python_client.models.inline_team import InlineTeam -from signrequest_python_client.models.inline_team_member import InlineTeamMember -from signrequest_python_client.models.invite_member import InviteMember -from signrequest_python_client.models.placeholder import Placeholder -from signrequest_python_client.models.required_attachment import RequiredAttachment -from signrequest_python_client.models.sign_request import SignRequest -from signrequest_python_client.models.sign_request_quick_create import SignRequestQuickCreate -from signrequest_python_client.models.signer import Signer -from signrequest_python_client.models.signer_attachment import SignerAttachment -from signrequest_python_client.models.signer_inputs import SignerInputs -from signrequest_python_client.models.signing_log import SigningLog -from signrequest_python_client.models.team import Team -from signrequest_python_client.models.team_member import TeamMember -from signrequest_python_client.models.template import Template -from signrequest_python_client.models.user import User -from signrequest_python_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_python_client/api/__init__.py b/signrequest_python_client/api/__init__.py deleted file mode 100644 index 1acff6e..0000000 --- a/signrequest_python_client/api/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -from __future__ import absolute_import - -# flake8: noqa - -# import apis into api package -from signrequest_python_client.api.api_tokens_api import ApiTokensApi -from signrequest_python_client.api.document_attachments_api import DocumentAttachmentsApi -from signrequest_python_client.api.documents_api import DocumentsApi -from signrequest_python_client.api.documents_search_api import DocumentsSearchApi -from signrequest_python_client.api.events_api import EventsApi -from signrequest_python_client.api.signrequest_quick_create_api import SignrequestQuickCreateApi -from signrequest_python_client.api.signrequests_api import SignrequestsApi -from signrequest_python_client.api.team_members_api import TeamMembersApi -from signrequest_python_client.api.teams_api import TeamsApi -from signrequest_python_client.api.templates_api import TemplatesApi -from signrequest_python_client.api.webhooks_api import WebhooksApi diff --git a/signrequest_python_client/api/api_tokens_api.py b/signrequest_python_client/api/api_tokens_api.py deleted file mode 100644 index 14be6e1..0000000 --- a/signrequest_python_client/api/api_tokens_api.py +++ /dev/null @@ -1,430 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class ApiTokensApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def api_tokens_create(self, data, **kwargs): # noqa: E501 - """Create an API token # noqa: E501 - - You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param AuthToken data: (required) - :return: AuthToken - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.api_tokens_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def api_tokens_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create an API token # noqa: E501 - - You can create an API token in the [team api settings page](/#/teams). It is also possible to get or create a token using the REST api with your login credentials. # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param AuthToken data: (required) - :return: AuthToken - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method api_tokens_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `api_tokens_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/api-tokens/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='AuthToken', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def api_tokens_delete(self, key, **kwargs): # noqa: E501 - """Delete an API token # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_delete(key, async=True) - >>> result = thread.get() - - :param async bool - :param str key: A unique value identifying this api token. (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 - else: - (data) = self.api_tokens_delete_with_http_info(key, **kwargs) # noqa: E501 - return data - - def api_tokens_delete_with_http_info(self, key, **kwargs): # noqa: E501 - """Delete an API token # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_delete_with_http_info(key, async=True) - >>> result = thread.get() - - :param async bool - :param str key: A unique value identifying this api token. (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['key'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method api_tokens_delete" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'key' is set - if ('key' not in params or - params['key'] is None): - raise ValueError("Missing the required parameter `key` when calling `api_tokens_delete`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'key' in params: - path_params['key'] = params['key'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/api-tokens/{key}/', 'DELETE', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type=None, # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def api_tokens_list(self, **kwargs): # noqa: E501 - """Retrieve a list of API tokens # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_list(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse200 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.api_tokens_list_with_http_info(**kwargs) # noqa: E501 - return data - - def api_tokens_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of API tokens # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse200 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method api_tokens_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/api-tokens/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse200', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def api_tokens_read(self, key, **kwargs): # noqa: E501 - """Retrieve an API token # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_read(key, async=True) - >>> result = thread.get() - - :param async bool - :param str key: A unique value identifying this api token. (required) - :return: AuthToken - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 - else: - (data) = self.api_tokens_read_with_http_info(key, **kwargs) # noqa: E501 - return data - - def api_tokens_read_with_http_info(self, key, **kwargs): # noqa: E501 - """Retrieve an API token # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.api_tokens_read_with_http_info(key, async=True) - >>> result = thread.get() - - :param async bool - :param str key: A unique value identifying this api token. (required) - :return: AuthToken - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['key'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method api_tokens_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'key' is set - if ('key' not in params or - params['key'] is None): - raise ValueError("Missing the required parameter `key` when calling `api_tokens_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'key' in params: - path_params['key'] = params['key'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/api-tokens/{key}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='AuthToken', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/document_attachments_api.py b/signrequest_python_client/api/document_attachments_api.py deleted file mode 100644 index 3e05d80..0000000 --- a/signrequest_python_client/api/document_attachments_api.py +++ /dev/null @@ -1,343 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class DocumentAttachmentsApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def document_attachments_create(self, data, **kwargs): # noqa: E501 - """Create a Document Attachment # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param DocumentAttachment data: (required) - :return: DocumentAttachment - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.document_attachments_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def document_attachments_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create a Document Attachment # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param DocumentAttachment data: (required) - :return: DocumentAttachment - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method document_attachments_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `document_attachments_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/document-attachments/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='DocumentAttachment', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def document_attachments_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Document Attachments # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_list(async=True) - >>> result = thread.get() - - :param async bool - :param str document__uuid: - :param str document__external_id: - :param str created: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2001 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.document_attachments_list_with_http_info(**kwargs) # noqa: E501 - return data - - def document_attachments_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Document Attachments # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param str document__uuid: - :param str document__external_id: - :param str created: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2001 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['document__uuid', 'document__external_id', 'created', 'page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method document_attachments_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'document__uuid' in params: - query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 - if 'document__external_id' in params: - query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 - if 'created' in params: - query_params.append(('created', params['created'])) # noqa: E501 - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/document-attachments/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2001', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def document_attachments_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Document Attachment # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: DocumentAttachment - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.document_attachments_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def document_attachments_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Document Attachment # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.document_attachments_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: DocumentAttachment - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method document_attachments_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `document_attachments_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/document-attachments/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='DocumentAttachment', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/documents_api.py b/signrequest_python_client/api/documents_api.py deleted file mode 100644 index 7859e27..0000000 --- a/signrequest_python_client/api/documents_api.py +++ /dev/null @@ -1,466 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class DocumentsApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def documents_create(self, data, **kwargs): # noqa: E501 - """Create a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param Document data: (required) - :return: Document - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.documents_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.documents_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def documents_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param Document data: (required) - :return: Document - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method documents_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `documents_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/documents/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Document', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def documents_delete(self, uuid, **kwargs): # noqa: E501 - """Delete a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_delete(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.documents_delete_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def documents_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Delete a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_delete_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method documents_delete" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `documents_delete`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/documents/{uuid}/', 'DELETE', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type=None, # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def documents_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Documents # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_list(async=True) - >>> result = thread.get() - - :param async bool - :param str external_id: - :param str signrequest__who: - :param str signrequest__from_email: - :param str status: - :param str user__email: - :param str user__first_name: - :param str user__last_name: - :param str created: - :param str modified: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2003 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.documents_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.documents_list_with_http_info(**kwargs) # noqa: E501 - return data - - def documents_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Documents # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param str external_id: - :param str signrequest__who: - :param str signrequest__from_email: - :param str status: - :param str user__email: - :param str user__first_name: - :param str user__last_name: - :param str created: - :param str modified: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2003 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['external_id', 'signrequest__who', 'signrequest__from_email', 'status', 'user__email', 'user__first_name', 'user__last_name', 'created', 'modified', 'page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method documents_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'external_id' in params: - query_params.append(('external_id', params['external_id'])) # noqa: E501 - if 'signrequest__who' in params: - query_params.append(('signrequest__who', params['signrequest__who'])) # noqa: E501 - if 'signrequest__from_email' in params: - query_params.append(('signrequest__from_email', params['signrequest__from_email'])) # noqa: E501 - if 'status' in params: - query_params.append(('status', params['status'])) # noqa: E501 - if 'user__email' in params: - query_params.append(('user__email', params['user__email'])) # noqa: E501 - if 'user__first_name' in params: - query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 - if 'user__last_name' in params: - query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 - if 'created' in params: - query_params.append(('created', params['created'])) # noqa: E501 - if 'modified' in params: - query_params.append(('modified', params['modified'])) # noqa: E501 - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/documents/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2003', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def documents_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: Document - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.documents_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def documents_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Document # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: Document - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method documents_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `documents_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/documents/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Document', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/documents_search_api.py b/signrequest_python_client/api/documents_search_api.py deleted file mode 100644 index eace5f3..0000000 --- a/signrequest_python_client/api/documents_search_api.py +++ /dev/null @@ -1,169 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class DocumentsSearchApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def documents_search_list(self, **kwargs): # noqa: E501 - """Search documents # noqa: E501 - - Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_search_list(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :param str q: Normal search query - :param str autocomplete: Partial search query - :param str name: Document name - :param str subdomain: - :param str signer_emails: Email needed to sign/approve - :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired - :param str who: `m`: only me, `mo`: me and others, `o`: only others - :param str format: Export format, can be `json` (default), `csv`, or `xls` - :param float signer_data: Set to `1` to export with each signer on a separate row - :return: InlineResponse2002 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.documents_search_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.documents_search_list_with_http_info(**kwargs) # noqa: E501 - return data - - def documents_search_list_with_http_info(self, **kwargs): # noqa: E501 - """Search documents # noqa: E501 - - Search interface for fast (autocomplete) searching of documents. This can be useful to have your users search for a document in your interface. Document names are tokenized on whitespace, hyphens and underscores to also match partial document names. *Normal search:* - ?**q**={{query}} *Autocomplete search:* - ?**autocomplete**={{partial query}} *Search in document name:* - ?**name**={{query}} *Available (extra) filters:* - ?**subdomain**={{ team_subdomain }} or use this endpoint with team_subdomain.signrequest.com (when not provided only personal documents are shown) - ?**signer_emails**={{ signer@email.com }} (will filter documents that an email needed to sign/approve) - ?**status**={{ si }} - ?**who**={{ mo }} To include multiple values for a filter field separate the values with a pipe (|). For example to only search for completed documents use **status=se|vi** (sent and viewed). *Pagination:* - ?**page**={{ page_number: default 1 }} - ?**limit**={{ limit results: default 10, max 100 }} *Format:* By default json is returned, to export data as csv or xls use the format parameter. - ?**format**=csv - ?**format**=xls For csv and xls the data can also be exported with each signer on a separate row. In this mode also the signer inputs that have an *external_id* specified on a tag will be exported. All external_id's found will be exported as columns. To use this mode add the **signer_data** parameter. - ?**format**=csv&**signer_data**=1 - ?**format**=xls&**signer_data**=1 Note that all documents are only ordered by **created** (newest first) when **q**, **autocomplete** or **name** are not used, else they are ordered by the strenght of the match. # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.documents_search_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :param str q: Normal search query - :param str autocomplete: Partial search query - :param str name: Document name - :param str subdomain: - :param str signer_emails: Email needed to sign/approve - :param str status: `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired - :param str who: `m`: only me, `mo`: me and others, `o`: only others - :param str format: Export format, can be `json` (default), `csv`, or `xls` - :param float signer_data: Set to `1` to export with each signer on a separate row - :return: InlineResponse2002 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['page', 'limit', 'q', 'autocomplete', 'name', 'subdomain', 'signer_emails', 'status', 'who', 'format', 'signer_data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method documents_search_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - if 'q' in params: - query_params.append(('q', params['q'])) # noqa: E501 - if 'autocomplete' in params: - query_params.append(('autocomplete', params['autocomplete'])) # noqa: E501 - if 'name' in params: - query_params.append(('name', params['name'])) # noqa: E501 - if 'subdomain' in params: - query_params.append(('subdomain', params['subdomain'])) # noqa: E501 - if 'signer_emails' in params: - query_params.append(('signer_emails', params['signer_emails'])) # noqa: E501 - if 'status' in params: - query_params.append(('status', params['status'])) # noqa: E501 - if 'who' in params: - query_params.append(('who', params['who'])) # noqa: E501 - if 'format' in params: - query_params.append(('format', params['format'])) # noqa: E501 - if 'signer_data' in params: - query_params.append(('signer_data', params['signer_data'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json', 'text/csv', 'application/vnd.ms-excel']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/documents-search/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2002', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/events_api.py b/signrequest_python_client/api/events_api.py deleted file mode 100644 index 73207f9..0000000 --- a/signrequest_python_client/api/events_api.py +++ /dev/null @@ -1,284 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class EventsApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def events_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Events # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.events_list(async=True) - >>> result = thread.get() - - :param async bool - :param str document__uuid: - :param str document__external_id: - :param str document__signrequest__who: - :param str document__signrequest__from_email: - :param str document__status: - :param str document__user__email: - :param str document__user__first_name: - :param str document__user__last_name: - :param str delivered: - :param str delivered_on: - :param str timestamp: - :param str status: - :param str event_type: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2004 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.events_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.events_list_with_http_info(**kwargs) # noqa: E501 - return data - - def events_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Events # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.events_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param str document__uuid: - :param str document__external_id: - :param str document__signrequest__who: - :param str document__signrequest__from_email: - :param str document__status: - :param str document__user__email: - :param str document__user__first_name: - :param str document__user__last_name: - :param str delivered: - :param str delivered_on: - :param str timestamp: - :param str status: - :param str event_type: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2004 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['document__uuid', 'document__external_id', 'document__signrequest__who', 'document__signrequest__from_email', 'document__status', 'document__user__email', 'document__user__first_name', 'document__user__last_name', 'delivered', 'delivered_on', 'timestamp', 'status', 'event_type', 'page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method events_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'document__uuid' in params: - query_params.append(('document__uuid', params['document__uuid'])) # noqa: E501 - if 'document__external_id' in params: - query_params.append(('document__external_id', params['document__external_id'])) # noqa: E501 - if 'document__signrequest__who' in params: - query_params.append(('document__signrequest__who', params['document__signrequest__who'])) # noqa: E501 - if 'document__signrequest__from_email' in params: - query_params.append(('document__signrequest__from_email', params['document__signrequest__from_email'])) # noqa: E501 - if 'document__status' in params: - query_params.append(('document__status', params['document__status'])) # noqa: E501 - if 'document__user__email' in params: - query_params.append(('document__user__email', params['document__user__email'])) # noqa: E501 - if 'document__user__first_name' in params: - query_params.append(('document__user__first_name', params['document__user__first_name'])) # noqa: E501 - if 'document__user__last_name' in params: - query_params.append(('document__user__last_name', params['document__user__last_name'])) # noqa: E501 - if 'delivered' in params: - query_params.append(('delivered', params['delivered'])) # noqa: E501 - if 'delivered_on' in params: - query_params.append(('delivered_on', params['delivered_on'])) # noqa: E501 - if 'timestamp' in params: - query_params.append(('timestamp', params['timestamp'])) # noqa: E501 - if 'status' in params: - query_params.append(('status', params['status'])) # noqa: E501 - if 'event_type' in params: - query_params.append(('event_type', params['event_type'])) # noqa: E501 - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/events/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2004', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def events_read(self, id, **kwargs): # noqa: E501 - """Retrieve an Event # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.events_read(id, async=True) - >>> result = thread.get() - - :param async bool - :param int id: A unique integer value identifying this event. (required) - :return: Event - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.events_read_with_http_info(id, **kwargs) # noqa: E501 - else: - (data) = self.events_read_with_http_info(id, **kwargs) # noqa: E501 - return data - - def events_read_with_http_info(self, id, **kwargs): # noqa: E501 - """Retrieve an Event # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.events_read_with_http_info(id, async=True) - >>> result = thread.get() - - :param async bool - :param int id: A unique integer value identifying this event. (required) - :return: Event - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['id'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method events_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'id' is set - if ('id' not in params or - params['id'] is None): - raise ValueError("Missing the required parameter `id` when calling `events_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'id' in params: - path_params['id'] = params['id'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/events/{id}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Event', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/signrequest_quick_create_api.py b/signrequest_python_client/api/signrequest_quick_create_api.py deleted file mode 100644 index de57a6e..0000000 --- a/signrequest_python_client/api/signrequest_quick_create_api.py +++ /dev/null @@ -1,133 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class SignrequestQuickCreateApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def signrequest_quick_create_create(self, data, **kwargs): # noqa: E501 - """Quick create a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequest_quick_create_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param SignRequestQuickCreate data: (required) - :return: SignRequestQuickCreate - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.signrequest_quick_create_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def signrequest_quick_create_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Quick create a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequest_quick_create_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param SignRequestQuickCreate data: (required) - :return: SignRequestQuickCreate - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequest_quick_create_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `signrequest_quick_create_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequest-quick-create/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='SignRequestQuickCreate', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/signrequests_api.py b/signrequest_python_client/api/signrequests_api.py deleted file mode 100644 index 3d43314..0000000 --- a/signrequest_python_client/api/signrequests_api.py +++ /dev/null @@ -1,537 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class SignrequestsApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def signrequests_cancel_signrequest(self, uuid, **kwargs): # noqa: E501 - """Cancel a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_cancel_signrequest(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: InlineResponse201 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.signrequests_cancel_signrequest_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def signrequests_cancel_signrequest_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Cancel a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_cancel_signrequest_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: InlineResponse201 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequests_cancel_signrequest" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `signrequests_cancel_signrequest`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequests/{uuid}/cancel_signrequest/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse201', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def signrequests_create(self, data, **kwargs): # noqa: E501 - """Create a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param SignRequest data: (required) - :return: SignRequest - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.signrequests_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def signrequests_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param SignRequest data: (required) - :return: SignRequest - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequests_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `signrequests_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequests/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='SignRequest', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def signrequests_list(self, **kwargs): # noqa: E501 - """Retrieve a list of SignRequests # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_list(async=True) - >>> result = thread.get() - - :param async bool - :param str who: - :param str from_email: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2005 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequests_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.signrequests_list_with_http_info(**kwargs) # noqa: E501 - return data - - def signrequests_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of SignRequests # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param str who: - :param str from_email: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2005 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['who', 'from_email', 'page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequests_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'who' in params: - query_params.append(('who', params['who'])) # noqa: E501 - if 'from_email' in params: - query_params.append(('from_email', params['from_email'])) # noqa: E501 - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequests/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2005', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def signrequests_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: SignRequest - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.signrequests_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def signrequests_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: SignRequest - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequests_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `signrequests_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequests/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='SignRequest', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def signrequests_resend_signrequest_email(self, uuid, **kwargs): # noqa: E501 - """Resend a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_resend_signrequest_email(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: InlineResponse2011 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.signrequests_resend_signrequest_email_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def signrequests_resend_signrequest_email_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Resend a SignRequest # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.signrequests_resend_signrequest_email_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: InlineResponse2011 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method signrequests_resend_signrequest_email" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `signrequests_resend_signrequest_email`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/signrequests/{uuid}/resend_signrequest_email/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2011', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/team_members_api.py b/signrequest_python_client/api/team_members_api.py deleted file mode 100644 index 7cd70f0..0000000 --- a/signrequest_python_client/api/team_members_api.py +++ /dev/null @@ -1,256 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class TeamMembersApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def team_members_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Team Members # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.team_members_list(async=True) - >>> result = thread.get() - - :param async bool - :param str is_active: - :param str is_owner: - :param str is_admin: - :param str user__email: - :param str user__first_name: - :param str user__last_name: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2006 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.team_members_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.team_members_list_with_http_info(**kwargs) # noqa: E501 - return data - - def team_members_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Team Members # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.team_members_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param str is_active: - :param str is_owner: - :param str is_admin: - :param str user__email: - :param str user__first_name: - :param str user__last_name: - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2006 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['is_active', 'is_owner', 'is_admin', 'user__email', 'user__first_name', 'user__last_name', 'page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method team_members_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'is_active' in params: - query_params.append(('is_active', params['is_active'])) # noqa: E501 - if 'is_owner' in params: - query_params.append(('is_owner', params['is_owner'])) # noqa: E501 - if 'is_admin' in params: - query_params.append(('is_admin', params['is_admin'])) # noqa: E501 - if 'user__email' in params: - query_params.append(('user__email', params['user__email'])) # noqa: E501 - if 'user__first_name' in params: - query_params.append(('user__first_name', params['user__first_name'])) # noqa: E501 - if 'user__last_name' in params: - query_params.append(('user__last_name', params['user__last_name'])) # noqa: E501 - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/team-members/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2006', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def team_members_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Team Member # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.team_members_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: TeamMember - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.team_members_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def team_members_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Team Member # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.team_members_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: TeamMember - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method team_members_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `team_members_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/team-members/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='TeamMember', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/teams_api.py b/signrequest_python_client/api/teams_api.py deleted file mode 100644 index 5f50a27..0000000 --- a/signrequest_python_client/api/teams_api.py +++ /dev/null @@ -1,545 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class TeamsApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def teams_create(self, data, **kwargs): # noqa: E501 - """Create a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param Team data: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.teams_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.teams_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def teams_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param Team data: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method teams_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `teams_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/teams/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Team', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def teams_invite_member(self, subdomain, data, **kwargs): # noqa: E501 - """Invite a Team Member # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_invite_member(subdomain, data, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :param InviteMember data: (required) - :return: InviteMember - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 - else: - (data) = self.teams_invite_member_with_http_info(subdomain, data, **kwargs) # noqa: E501 - return data - - def teams_invite_member_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 - """Invite a Team Member # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_invite_member_with_http_info(subdomain, data, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :param InviteMember data: (required) - :return: InviteMember - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['subdomain', 'data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method teams_invite_member" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'subdomain' is set - if ('subdomain' not in params or - params['subdomain'] is None): - raise ValueError("Missing the required parameter `subdomain` when calling `teams_invite_member`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `teams_invite_member`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'subdomain' in params: - path_params['subdomain'] = params['subdomain'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/teams/{subdomain}/invite_member/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InviteMember', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def teams_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Teams # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_list(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2007 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.teams_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.teams_list_with_http_info(**kwargs) # noqa: E501 - return data - - def teams_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Teams # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2007 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method teams_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/teams/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2007', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def teams_partial_update(self, subdomain, data, **kwargs): # noqa: E501 - """Update a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_partial_update(subdomain, data, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :param Team data: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 - else: - (data) = self.teams_partial_update_with_http_info(subdomain, data, **kwargs) # noqa: E501 - return data - - def teams_partial_update_with_http_info(self, subdomain, data, **kwargs): # noqa: E501 - """Update a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_partial_update_with_http_info(subdomain, data, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :param Team data: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['subdomain', 'data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method teams_partial_update" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'subdomain' is set - if ('subdomain' not in params or - params['subdomain'] is None): - raise ValueError("Missing the required parameter `subdomain` when calling `teams_partial_update`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `teams_partial_update`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'subdomain' in params: - path_params['subdomain'] = params['subdomain'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/teams/{subdomain}/', 'PATCH', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Team', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def teams_read(self, subdomain, **kwargs): # noqa: E501 - """Retrieve a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_read(subdomain, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 - else: - (data) = self.teams_read_with_http_info(subdomain, **kwargs) # noqa: E501 - return data - - def teams_read_with_http_info(self, subdomain, **kwargs): # noqa: E501 - """Retrieve a Team # noqa: E501 - - Required fields are **name** and **subdomain** where the subdomain is globally unique. Use **POST** to create a Team. To update a field on a Team use **PATCH**. To use the API on behalf of a particular team change the endpoint to: *https://**{{ subdomain }}**.signrequest.com/api/v1/...* To invite new team members you can use **POST** {\"email\":\"**email-of-member-to-invite@example.com**\",\"is_admin\":false,\"is_owner\":false} to: *https://signrequest.com/api/v1/teams/**{{ subdomain }}**/invite_member/* # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.teams_read_with_http_info(subdomain, async=True) - >>> result = thread.get() - - :param async bool - :param str subdomain: (required) - :return: Team - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['subdomain'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method teams_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'subdomain' is set - if ('subdomain' not in params or - params['subdomain'] is None): - raise ValueError("Missing the required parameter `subdomain` when calling `teams_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'subdomain' in params: - path_params['subdomain'] = params['subdomain'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/teams/{subdomain}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Team', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/templates_api.py b/signrequest_python_client/api/templates_api.py deleted file mode 100644 index ab50852..0000000 --- a/signrequest_python_client/api/templates_api.py +++ /dev/null @@ -1,232 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class TemplatesApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def templates_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Templates # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.templates_list(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2008 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.templates_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.templates_list_with_http_info(**kwargs) # noqa: E501 - return data - - def templates_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Templates # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.templates_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2008 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method templates_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/templates/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2008', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def templates_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Template # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.templates_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: Template - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.templates_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def templates_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Template # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.templates_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: Template - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method templates_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `templates_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/templates/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='Template', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api/webhooks_api.py b/signrequest_python_client/api/webhooks_api.py deleted file mode 100644 index 6c088dd..0000000 --- a/signrequest_python_client/api/webhooks_api.py +++ /dev/null @@ -1,644 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import re # noqa: F401 - -# python 2 and python 3 compatibility library -import six - -from signrequest_python_client.api_client import ApiClient - - -class WebhooksApi(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - Ref: https://github.com/swagger-api/swagger-codegen - """ - - def __init__(self, api_client=None): - if api_client is None: - api_client = ApiClient() - self.api_client = api_client - - def webhooks_create(self, data, **kwargs): # noqa: E501 - """Create a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_create(data, async=True) - >>> result = thread.get() - - :param async bool - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 - else: - (data) = self.webhooks_create_with_http_info(data, **kwargs) # noqa: E501 - return data - - def webhooks_create_with_http_info(self, data, **kwargs): # noqa: E501 - """Create a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_create_with_http_info(data, async=True) - >>> result = thread.get() - - :param async bool - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_create" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `webhooks_create`") # noqa: E501 - - collection_formats = {} - - path_params = {} - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/', 'POST', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='WebhookSubscription', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def webhooks_delete(self, uuid, **kwargs): # noqa: E501 - """Delete a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_delete(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.webhooks_delete_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def webhooks_delete_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Delete a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_delete_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: None - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_delete" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `webhooks_delete`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/{uuid}/', 'DELETE', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type=None, # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def webhooks_list(self, **kwargs): # noqa: E501 - """Retrieve a list of Webhooks # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_list(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2009 - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_list_with_http_info(**kwargs) # noqa: E501 - else: - (data) = self.webhooks_list_with_http_info(**kwargs) # noqa: E501 - return data - - def webhooks_list_with_http_info(self, **kwargs): # noqa: E501 - """Retrieve a list of Webhooks # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_list_with_http_info(async=True) - >>> result = thread.get() - - :param async bool - :param int page: A page number within the paginated result set. - :param int limit: Number of results to return per page. - :return: InlineResponse2009 - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['page', 'limit'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_list" % key - ) - params[key] = val - del params['kwargs'] - - collection_formats = {} - - path_params = {} - - query_params = [] - if 'page' in params: - query_params.append(('page', params['page'])) # noqa: E501 - if 'limit' in params: - query_params.append(('limit', params['limit'])) # noqa: E501 - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='InlineResponse2009', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def webhooks_partial_update(self, uuid, data, **kwargs): # noqa: E501 - """Partially update a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_partial_update(uuid, data, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 - else: - (data) = self.webhooks_partial_update_with_http_info(uuid, data, **kwargs) # noqa: E501 - return data - - def webhooks_partial_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 - """Partially update a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_partial_update_with_http_info(uuid, data, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid', 'data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_partial_update" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `webhooks_partial_update`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `webhooks_partial_update`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/{uuid}/', 'PATCH', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='WebhookSubscription', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def webhooks_read(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_read(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 - else: - (data) = self.webhooks_read_with_http_info(uuid, **kwargs) # noqa: E501 - return data - - def webhooks_read_with_http_info(self, uuid, **kwargs): # noqa: E501 - """Retrieve a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_read_with_http_info(uuid, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_read" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `webhooks_read`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/{uuid}/', 'GET', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='WebhookSubscription', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) - - def webhooks_update(self, uuid, data, **kwargs): # noqa: E501 - """Update a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_update(uuid, data, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - kwargs['_return_http_data_only'] = True - if kwargs.get('async'): - return self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 - else: - (data) = self.webhooks_update_with_http_info(uuid, data, **kwargs) # noqa: E501 - return data - - def webhooks_update_with_http_info(self, uuid, data, **kwargs): # noqa: E501 - """Update a Webhook # noqa: E501 - - # noqa: E501 - This method makes a synchronous HTTP request by default. To make an - asynchronous HTTP request, please pass async=True - >>> thread = api.webhooks_update_with_http_info(uuid, data, async=True) - >>> result = thread.get() - - :param async bool - :param str uuid: (required) - :param WebhookSubscription data: (required) - :return: WebhookSubscription - If the method is called asynchronously, - returns the request thread. - """ - - all_params = ['uuid', 'data'] # noqa: E501 - all_params.append('async') - all_params.append('_return_http_data_only') - all_params.append('_preload_content') - all_params.append('_request_timeout') - - params = locals() - for key, val in six.iteritems(params['kwargs']): - if key not in all_params: - raise TypeError( - "Got an unexpected keyword argument '%s'" - " to method webhooks_update" % key - ) - params[key] = val - del params['kwargs'] - # verify the required parameter 'uuid' is set - if ('uuid' not in params or - params['uuid'] is None): - raise ValueError("Missing the required parameter `uuid` when calling `webhooks_update`") # noqa: E501 - # verify the required parameter 'data' is set - if ('data' not in params or - params['data'] is None): - raise ValueError("Missing the required parameter `data` when calling `webhooks_update`") # noqa: E501 - - collection_formats = {} - - path_params = {} - if 'uuid' in params: - path_params['uuid'] = params['uuid'] # noqa: E501 - - query_params = [] - - header_params = {} - - form_params = [] - local_var_files = {} - - body_params = None - if 'data' in params: - body_params = params['data'] - # HTTP header `Accept` - header_params['Accept'] = self.api_client.select_header_accept( - ['application/json']) # noqa: E501 - - # HTTP header `Content-Type` - header_params['Content-Type'] = self.api_client.select_header_content_type( # noqa: E501 - ['application/json']) # noqa: E501 - - # Authentication setting - auth_settings = ['Token'] # noqa: E501 - - return self.api_client.call_api( - '/webhooks/{uuid}/', 'PUT', - path_params, - query_params, - header_params, - body=body_params, - post_params=form_params, - files=local_var_files, - response_type='WebhookSubscription', # noqa: E501 - auth_settings=auth_settings, - async=params.get('async'), - _return_http_data_only=params.get('_return_http_data_only'), - _preload_content=params.get('_preload_content', True), - _request_timeout=params.get('_request_timeout'), - collection_formats=collection_formats) diff --git a/signrequest_python_client/api_client.py b/signrequest_python_client/api_client.py deleted file mode 100644 index 6ad4a6c..0000000 --- a/signrequest_python_client/api_client.py +++ /dev/null @@ -1,621 +0,0 @@ -# coding: utf-8 -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - -from __future__ import absolute_import - -import datetime -import json -import mimetypes -from multiprocessing.pool import ThreadPool -import os -import re -import tempfile - -# python 2 and python 3 compatibility library -import six -from six.moves.urllib.parse import quote - -from signrequest_python_client.configuration import Configuration -import signrequest_python_client.models -from signrequest_python_client import rest - - -class ApiClient(object): - """Generic API client for Swagger client library builds. - - Swagger generic API client. This client handles the client- - server communication, and is invariant across implementations. Specifics of - the methods and models for each application are generated from the Swagger - templates. - - NOTE: This class is auto generated by the swagger code generator program. - Ref: https://github.com/swagger-api/swagger-codegen - Do not edit the class manually. - - :param configuration: .Configuration object for this client - :param header_name: a header to pass when making calls to the API. - :param header_value: a header value to pass when making calls to - the API. - :param cookie: a cookie to include in the header when making calls - to the API - """ - - PRIMITIVE_TYPES = (float, bool, bytes, six.text_type) + six.integer_types - NATIVE_TYPES_MAPPING = { - 'int': int, - 'long': int if six.PY3 else long, # noqa: F821 - 'float': float, - 'str': str, - 'bool': bool, - 'date': datetime.date, - 'datetime': datetime.datetime, - 'object': object, - } - - def __init__(self, configuration=None, header_name=None, header_value=None, - cookie=None): - if configuration is None: - configuration = Configuration() - self.configuration = configuration - - self.pool = ThreadPool() - self.rest_client = rest.RESTClientObject(configuration) - self.default_headers = {} - if header_name is not None: - self.default_headers[header_name] = header_value - self.cookie = cookie - # Set default User-Agent. - self.user_agent = 'Swagger-Codegen/2.0.0/python' - - def __del__(self): - self.pool.close() - self.pool.join() - - @property - def user_agent(self): - """User agent for this API client""" - return self.default_headers['User-Agent'] - - @user_agent.setter - def user_agent(self, value): - self.default_headers['User-Agent'] = value - - def set_default_header(self, header_name, header_value): - self.default_headers[header_name] = header_value - - def __call_api( - self, resource_path, method, path_params=None, - query_params=None, header_params=None, body=None, post_params=None, - files=None, response_type=None, auth_settings=None, - _return_http_data_only=None, collection_formats=None, - _preload_content=True, _request_timeout=None): - - config = self.configuration - - # header parameters - header_params = header_params or {} - header_params.update(self.default_headers) - if self.cookie: - header_params['Cookie'] = self.cookie - if header_params: - header_params = self.sanitize_for_serialization(header_params) - header_params = dict(self.parameters_to_tuples(header_params, - collection_formats)) - - # path parameters - if path_params: - path_params = self.sanitize_for_serialization(path_params) - path_params = self.parameters_to_tuples(path_params, - collection_formats) - for k, v in path_params: - # specified safe chars, encode everything - resource_path = resource_path.replace( - '{%s}' % k, - quote(str(v), safe=config.safe_chars_for_path_param) - ) - - # query parameters - if query_params: - query_params = self.sanitize_for_serialization(query_params) - query_params = self.parameters_to_tuples(query_params, - collection_formats) - - # post parameters - if post_params or files: - post_params = self.prepare_post_parameters(post_params, files) - post_params = self.sanitize_for_serialization(post_params) - post_params = self.parameters_to_tuples(post_params, - collection_formats) - - # auth setting - self.update_params_for_auth(header_params, query_params, auth_settings) - - # body - if body: - body = self.sanitize_for_serialization(body) - - # request url - url = self.configuration.host + resource_path - - # perform request and return response - response_data = self.request( - method, url, query_params=query_params, headers=header_params, - post_params=post_params, body=body, - _preload_content=_preload_content, - _request_timeout=_request_timeout) - - self.last_response = response_data - - return_data = response_data - if _preload_content: - # deserialize response data - if response_type: - return_data = self.deserialize(response_data, response_type) - else: - return_data = None - - if _return_http_data_only: - return (return_data) - else: - return (return_data, response_data.status, - response_data.getheaders()) - - def sanitize_for_serialization(self, obj): - """Builds a JSON POST object. - - If obj is None, return None. - If obj is str, int, long, float, bool, return directly. - If obj is datetime.datetime, datetime.date - convert to string in iso8601 format. - If obj is list, sanitize each element in the list. - If obj is dict, return the dict. - If obj is swagger model, return the properties dict. - - :param obj: The data to serialize. - :return: The serialized form of data. - """ - if obj is None: - return None - elif isinstance(obj, self.PRIMITIVE_TYPES): - return obj - elif isinstance(obj, list): - return [self.sanitize_for_serialization(sub_obj) - for sub_obj in obj] - elif isinstance(obj, tuple): - return tuple(self.sanitize_for_serialization(sub_obj) - for sub_obj in obj) - elif isinstance(obj, (datetime.datetime, datetime.date)): - return obj.isoformat() - - if isinstance(obj, dict): - obj_dict = obj - else: - # Convert model obj to dict except - # attributes `swagger_types`, `attribute_map` - # and attributes which value is not None. - # Convert attribute name to json key in - # model definition for request. - obj_dict = {obj.attribute_map[attr]: getattr(obj, attr) - for attr, _ in six.iteritems(obj.swagger_types) - if getattr(obj, attr) is not None} - - return {key: self.sanitize_for_serialization(val) - for key, val in six.iteritems(obj_dict)} - - def deserialize(self, response, response_type): - """Deserializes response into an object. - - :param response: RESTResponse object to be deserialized. - :param response_type: class literal for - deserialized object, or string of class name. - - :return: deserialized object. - """ - # handle file downloading - # save response body into a tmp file and return the instance - if response_type == "file": - return self.__deserialize_file(response) - - # fetch data from response object - try: - data = json.loads(response.data) - except ValueError: - data = response.data - - return self.__deserialize(data, response_type) - - def __deserialize(self, data, klass): - """Deserializes dict, list, str into an object. - - :param data: dict, list or str. - :param klass: class literal, or string of class name. - - :return: object. - """ - if data is None: - return None - - if type(klass) == str: - if klass.startswith('list['): - sub_kls = re.match('list\[(.*)\]', klass).group(1) - return [self.__deserialize(sub_data, sub_kls) - for sub_data in data] - - if klass.startswith('dict('): - sub_kls = re.match('dict\(([^,]*), (.*)\)', klass).group(2) - return {k: self.__deserialize(v, sub_kls) - for k, v in six.iteritems(data)} - - # convert str to class - if klass in self.NATIVE_TYPES_MAPPING: - klass = self.NATIVE_TYPES_MAPPING[klass] - else: - klass = getattr(signrequest_python_client.models, klass) - - if klass in self.PRIMITIVE_TYPES: - return self.__deserialize_primitive(data, klass) - elif klass == object: - return self.__deserialize_object(data) - elif klass == datetime.date: - return self.__deserialize_date(data) - elif klass == datetime.datetime: - return self.__deserialize_datatime(data) - else: - return self.__deserialize_model(data, klass) - - def call_api(self, resource_path, method, - path_params=None, query_params=None, header_params=None, - body=None, post_params=None, files=None, - response_type=None, auth_settings=None, async=None, - _return_http_data_only=None, collection_formats=None, - _preload_content=True, _request_timeout=None): - """Makes the HTTP request (synchronous) and returns deserialized data. - - To make an async request, set the async parameter. - - :param resource_path: Path to method endpoint. - :param method: Method to call. - :param path_params: Path parameters in the url. - :param query_params: Query parameters in the url. - :param header_params: Header parameters to be - placed in the request header. - :param body: Request body. - :param post_params dict: Request post form parameters, - for `application/x-www-form-urlencoded`, `multipart/form-data`. - :param auth_settings list: Auth Settings names for the request. - :param response: Response data type. - :param files dict: key -> filename, value -> filepath, - for `multipart/form-data`. - :param async bool: execute request asynchronously - :param _return_http_data_only: response data without head status code - and headers - :param collection_formats: dict of collection formats for path, query, - header, and post parameters. - :param _preload_content: if False, the urllib3.HTTPResponse object will - be returned without reading/decoding response - data. Default is True. - :param _request_timeout: timeout setting for this request. If one - number provided, it will be total request - timeout. It can also be a pair (tuple) of - (connection, read) timeouts. - :return: - If async parameter is True, - the request will be called asynchronously. - The method will return the request thread. - If parameter async is False or missing, - then the method will return the response directly. - """ - if not async: - return self.__call_api(resource_path, method, - path_params, query_params, header_params, - body, post_params, files, - response_type, auth_settings, - _return_http_data_only, collection_formats, - _preload_content, _request_timeout) - else: - thread = self.pool.apply_async(self.__call_api, (resource_path, - method, path_params, query_params, - header_params, body, - post_params, files, - response_type, auth_settings, - _return_http_data_only, - collection_formats, - _preload_content, _request_timeout)) - return thread - - def request(self, method, url, query_params=None, headers=None, - post_params=None, body=None, _preload_content=True, - _request_timeout=None): - """Makes the HTTP request using RESTClient.""" - if method == "GET": - return self.rest_client.GET(url, - query_params=query_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - headers=headers) - elif method == "HEAD": - return self.rest_client.HEAD(url, - query_params=query_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - headers=headers) - elif method == "OPTIONS": - return self.rest_client.OPTIONS(url, - query_params=query_params, - headers=headers, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - elif method == "POST": - return self.rest_client.POST(url, - query_params=query_params, - headers=headers, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - elif method == "PUT": - return self.rest_client.PUT(url, - query_params=query_params, - headers=headers, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - elif method == "PATCH": - return self.rest_client.PATCH(url, - query_params=query_params, - headers=headers, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - elif method == "DELETE": - return self.rest_client.DELETE(url, - query_params=query_params, - headers=headers, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - else: - raise ValueError( - "http method must be `GET`, `HEAD`, `OPTIONS`," - " `POST`, `PATCH`, `PUT` or `DELETE`." - ) - - def parameters_to_tuples(self, params, collection_formats): - """Get parameters as list of tuples, formatting collections. - - :param params: Parameters as dict or list of two-tuples - :param dict collection_formats: Parameter collection formats - :return: Parameters as list of tuples, collections formatted - """ - new_params = [] - if collection_formats is None: - collection_formats = {} - for k, v in six.iteritems(params) if isinstance(params, dict) else params: # noqa: E501 - if k in collection_formats: - collection_format = collection_formats[k] - if collection_format == 'multi': - new_params.extend((k, value) for value in v) - else: - if collection_format == 'ssv': - delimiter = ' ' - elif collection_format == 'tsv': - delimiter = '\t' - elif collection_format == 'pipes': - delimiter = '|' - else: # csv is the default - delimiter = ',' - new_params.append( - (k, delimiter.join(str(value) for value in v))) - else: - new_params.append((k, v)) - return new_params - - def prepare_post_parameters(self, post_params=None, files=None): - """Builds form parameters. - - :param post_params: Normal form parameters. - :param files: File parameters. - :return: Form parameters with files. - """ - params = [] - - if post_params: - params = post_params - - if files: - for k, v in six.iteritems(files): - if not v: - continue - file_names = v if type(v) is list else [v] - for n in file_names: - with open(n, 'rb') as f: - filename = os.path.basename(f.name) - filedata = f.read() - mimetype = (mimetypes.guess_type(filename)[0] or - 'application/octet-stream') - params.append( - tuple([k, tuple([filename, filedata, mimetype])])) - - return params - - def select_header_accept(self, accepts): - """Returns `Accept` based on an array of accepts provided. - - :param accepts: List of headers. - :return: Accept (e.g. application/json). - """ - if not accepts: - return - - accepts = [x.lower() for x in accepts] - - if 'application/json' in accepts: - return 'application/json' - else: - return ', '.join(accepts) - - def select_header_content_type(self, content_types): - """Returns `Content-Type` based on an array of content_types provided. - - :param content_types: List of content-types. - :return: Content-Type (e.g. application/json). - """ - if not content_types: - return 'application/json' - - content_types = [x.lower() for x in content_types] - - if 'application/json' in content_types or '*/*' in content_types: - return 'application/json' - else: - return content_types[0] - - def update_params_for_auth(self, headers, querys, auth_settings): - """Updates header and query params based on authentication setting. - - :param headers: Header parameters dict to be updated. - :param querys: Query parameters tuple list to be updated. - :param auth_settings: Authentication setting identifiers list. - """ - if not auth_settings: - return - - for auth in auth_settings: - auth_setting = self.configuration.auth_settings().get(auth) - if auth_setting: - if not auth_setting['value']: - continue - elif auth_setting['in'] == 'header': - headers[auth_setting['key']] = auth_setting['value'] - elif auth_setting['in'] == 'query': - querys.append((auth_setting['key'], auth_setting['value'])) - else: - raise ValueError( - 'Authentication token must be in `query` or `header`' - ) - - def __deserialize_file(self, response): - """Deserializes body to file - - Saves response body into a file in a temporary folder, - using the filename from the `Content-Disposition` header if provided. - - :param response: RESTResponse. - :return: file path. - """ - fd, path = tempfile.mkstemp(dir=self.configuration.temp_folder_path) - os.close(fd) - os.remove(path) - - content_disposition = response.getheader("Content-Disposition") - if content_disposition: - filename = re.search(r'filename=[\'"]?([^\'"\s]+)[\'"]?', - content_disposition).group(1) - path = os.path.join(os.path.dirname(path), filename) - - with open(path, "wb") as f: - f.write(response.data) - - return path - - def __deserialize_primitive(self, data, klass): - """Deserializes string to primitive type. - - :param data: str. - :param klass: class literal. - - :return: int, long, float, str, bool. - """ - try: - return klass(data) - except UnicodeEncodeError: - return six.u(data) - except TypeError: - return data - - def __deserialize_object(self, value): - """Return a original value. - - :return: object. - """ - return value - - def __deserialize_date(self, string): - """Deserializes string to date. - - :param string: str. - :return: date. - """ - try: - from dateutil.parser import parse - return parse(string).date() - except ImportError: - return string - except ValueError: - raise rest.ApiException( - status=0, - reason="Failed to parse `{0}` as date object".format(string) - ) - - def __deserialize_datatime(self, string): - """Deserializes string to datetime. - - The string should be in iso8601 datetime format. - - :param string: str. - :return: datetime. - """ - try: - from dateutil.parser import parse - return parse(string) - except ImportError: - return string - except ValueError: - raise rest.ApiException( - status=0, - reason=( - "Failed to parse `{0}` as datetime object" - .format(string) - ) - ) - - def __deserialize_model(self, data, klass): - """Deserializes list or dict to model. - - :param data: dict, list. - :param klass: class literal. - :return: model object. - """ - - if not klass.swagger_types and not hasattr(klass, - 'get_real_child_model'): - return data - - kwargs = {} - if klass.swagger_types is not None: - for attr, attr_type in six.iteritems(klass.swagger_types): - if (data is not None and - klass.attribute_map[attr] in data and - isinstance(data, (list, dict))): - value = data[klass.attribute_map[attr]] - kwargs[attr] = self.__deserialize(value, attr_type) - - instance = klass(**kwargs) - - if hasattr(instance, 'get_real_child_model'): - klass_name = instance.get_real_child_model(data) - if klass_name: - instance = self.__deserialize(data, klass_name) - return instance diff --git a/signrequest_python_client/configuration.py b/signrequest_python_client/configuration.py deleted file mode 100644 index 3a11624..0000000 --- a/signrequest_python_client/configuration.py +++ /dev/null @@ -1,247 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import copy -import logging -import multiprocessing -import sys -import urllib3 - -import six -from six.moves import http_client as httplib - - -class TypeWithDefault(type): - def __init__(cls, name, bases, dct): - super(TypeWithDefault, cls).__init__(name, bases, dct) - cls._default = None - - def __call__(cls): - if cls._default is None: - cls._default = type.__call__(cls) - return copy.copy(cls._default) - - def set_default(cls, default): - cls._default = copy.copy(default) - - -class Configuration(six.with_metaclass(TypeWithDefault, object)): - """NOTE: This class is auto generated by the swagger code generator program. - - Ref: https://github.com/swagger-api/swagger-codegen - Do not edit the class manually. - """ - - def __init__(self): - """Constructor""" - # Default Base url - self.host = "https://signrequest.com/api/v1" - # Temp file folder for downloading files - self.temp_folder_path = None - - # Authentication Settings - # dict to store API key(s) - self.api_key = {} - # dict to store API prefix (e.g. Bearer) - self.api_key_prefix = {} - # Username for HTTP basic authentication - self.username = "" - # Password for HTTP basic authentication - self.password = "" - - # Logging Settings - self.logger = {} - self.logger["package_logger"] = logging.getLogger("signrequest_python_client") - self.logger["urllib3_logger"] = logging.getLogger("urllib3") - # Log format - self.logger_format = '%(asctime)s %(levelname)s %(message)s' - # Log stream handler - self.logger_stream_handler = None - # Log file handler - self.logger_file_handler = None - # Debug file location - self.logger_file = None - # Debug switch - self.debug = False - - # SSL/TLS verification - # Set this to false to skip verifying SSL certificate when calling API - # from https server. - self.verify_ssl = True - # Set this to customize the certificate file to verify the peer. - self.ssl_ca_cert = None - # client certificate file - self.cert_file = None - # client key file - self.key_file = None - # Set this to True/False to enable/disable SSL hostname verification. - self.assert_hostname = None - - # urllib3 connection pool's maximum number of connections saved - # per pool. urllib3 uses 1 connection as default value, but this is - # not the best value when you are making a lot of possibly parallel - # requests to the same host, which is often the case here. - # cpu_count * 5 is used as default value to increase performance. - self.connection_pool_maxsize = multiprocessing.cpu_count() * 5 - - # Proxy URL - self.proxy = None - # Safe chars for path_param - self.safe_chars_for_path_param = '' - - @property - def logger_file(self): - """The logger file. - - If the logger_file is None, then add stream handler and remove file - handler. Otherwise, add file handler and remove stream handler. - - :param value: The logger_file path. - :type: str - """ - return self.__logger_file - - @logger_file.setter - def logger_file(self, value): - """The logger file. - - If the logger_file is None, then add stream handler and remove file - handler. Otherwise, add file handler and remove stream handler. - - :param value: The logger_file path. - :type: str - """ - self.__logger_file = value - if self.__logger_file: - # If set logging file, - # then add file handler and remove stream handler. - self.logger_file_handler = logging.FileHandler(self.__logger_file) - self.logger_file_handler.setFormatter(self.logger_formatter) - for _, logger in six.iteritems(self.logger): - logger.addHandler(self.logger_file_handler) - if self.logger_stream_handler: - logger.removeHandler(self.logger_stream_handler) - else: - # If not set logging file, - # then add stream handler and remove file handler. - self.logger_stream_handler = logging.StreamHandler() - self.logger_stream_handler.setFormatter(self.logger_formatter) - for _, logger in six.iteritems(self.logger): - logger.addHandler(self.logger_stream_handler) - if self.logger_file_handler: - logger.removeHandler(self.logger_file_handler) - - @property - def debug(self): - """Debug status - - :param value: The debug status, True or False. - :type: bool - """ - return self.__debug - - @debug.setter - def debug(self, value): - """Debug status - - :param value: The debug status, True or False. - :type: bool - """ - self.__debug = value - if self.__debug: - # if debug status is True, turn on debug logging - for _, logger in six.iteritems(self.logger): - logger.setLevel(logging.DEBUG) - # turn on httplib debug - httplib.HTTPConnection.debuglevel = 1 - else: - # if debug status is False, turn off debug logging, - # setting log level to default `logging.WARNING` - for _, logger in six.iteritems(self.logger): - logger.setLevel(logging.WARNING) - # turn off httplib debug - httplib.HTTPConnection.debuglevel = 0 - - @property - def logger_format(self): - """The logger format. - - The logger_formatter will be updated when sets logger_format. - - :param value: The format string. - :type: str - """ - return self.__logger_format - - @logger_format.setter - def logger_format(self, value): - """The logger format. - - The logger_formatter will be updated when sets logger_format. - - :param value: The format string. - :type: str - """ - self.__logger_format = value - self.logger_formatter = logging.Formatter(self.__logger_format) - - def get_api_key_with_prefix(self, identifier): - """Gets API key (with prefix if set). - - :param identifier: The identifier of apiKey. - :return: The token for api key authentication. - """ - if (self.api_key.get(identifier) and - self.api_key_prefix.get(identifier)): - return self.api_key_prefix[identifier] + ' ' + self.api_key[identifier] # noqa: E501 - elif self.api_key.get(identifier): - return self.api_key[identifier] - - def get_basic_auth_token(self): - """Gets HTTP basic authentication header (string). - - :return: The token for basic HTTP authentication. - """ - return urllib3.util.make_headers( - basic_auth=self.username + ':' + self.password - ).get('authorization') - - def auth_settings(self): - """Gets Auth Settings dict for api client. - - :return: The Auth Settings information dict. - """ - return { - 'Token': - { - 'type': 'api_key', - 'in': 'header', - 'key': 'Authorization', - 'value': self.get_api_key_with_prefix('Authorization') - }, - - } - - def to_debug_report(self): - """Gets the essential information for debugging. - - :return: The report for debugging. - """ - return "Python SDK Debug Report:\n"\ - "OS: {env}\n"\ - "Python Version: {pyversion}\n"\ - "Version of the API: v1\n"\ - "SDK Package Version: 2.0.0".\ - format(env=sys.platform, pyversion=sys.version) diff --git a/signrequest_python_client/models/__init__.py b/signrequest_python_client/models/__init__.py deleted file mode 100644 index c21ab44..0000000 --- a/signrequest_python_client/models/__init__.py +++ /dev/null @@ -1,56 +0,0 @@ -# coding: utf-8 - -# flake8: noqa -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -# import models into model package -from signrequest_python_client.models.auth_token import AuthToken -from signrequest_python_client.models.document import Document -from signrequest_python_client.models.document_attachment import DocumentAttachment -from signrequest_python_client.models.document_search import DocumentSearch -from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf -from signrequest_python_client.models.event import Event -from signrequest_python_client.models.file_from_sf import FileFromSf -from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData -from signrequest_python_client.models.inline_integration_data import InlineIntegrationData -from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags -from signrequest_python_client.models.inline_response_200 import InlineResponse200 -from signrequest_python_client.models.inline_response_200_1 import InlineResponse2001 -from signrequest_python_client.models.inline_response_200_2 import InlineResponse2002 -from signrequest_python_client.models.inline_response_200_3 import InlineResponse2003 -from signrequest_python_client.models.inline_response_200_4 import InlineResponse2004 -from signrequest_python_client.models.inline_response_200_5 import InlineResponse2005 -from signrequest_python_client.models.inline_response_200_6 import InlineResponse2006 -from signrequest_python_client.models.inline_response_200_7 import InlineResponse2007 -from signrequest_python_client.models.inline_response_200_8 import InlineResponse2008 -from signrequest_python_client.models.inline_response_200_9 import InlineResponse2009 -from signrequest_python_client.models.inline_response_201 import InlineResponse201 -from signrequest_python_client.models.inline_response_201_1 import InlineResponse2011 -from signrequest_python_client.models.inline_sign_request import InlineSignRequest -from signrequest_python_client.models.inline_team import InlineTeam -from signrequest_python_client.models.inline_team_member import InlineTeamMember -from signrequest_python_client.models.invite_member import InviteMember -from signrequest_python_client.models.placeholder import Placeholder -from signrequest_python_client.models.required_attachment import RequiredAttachment -from signrequest_python_client.models.sign_request import SignRequest -from signrequest_python_client.models.sign_request_quick_create import SignRequestQuickCreate -from signrequest_python_client.models.signer import Signer -from signrequest_python_client.models.signer_attachment import SignerAttachment -from signrequest_python_client.models.signer_inputs import SignerInputs -from signrequest_python_client.models.signing_log import SigningLog -from signrequest_python_client.models.team import Team -from signrequest_python_client.models.team_member import TeamMember -from signrequest_python_client.models.template import Template -from signrequest_python_client.models.user import User -from signrequest_python_client.models.webhook_subscription import WebhookSubscription diff --git a/signrequest_python_client/models/auth_token.py b/signrequest_python_client/models/auth_token.py deleted file mode 100644 index 5378f52..0000000 --- a/signrequest_python_client/models/auth_token.py +++ /dev/null @@ -1,251 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class AuthToken(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'email': 'str', - 'password': 'str', - 'subdomain': 'str', - 'name': 'str', - 'key': 'str', - 'url': 'str' - } - - attribute_map = { - 'email': 'email', - 'password': 'password', - 'subdomain': 'subdomain', - 'name': 'name', - 'key': 'key', - 'url': 'url' - } - - def __init__(self, email=None, password=None, subdomain=None, name=None, key=None, url=None): # noqa: E501 - """AuthToken - a model defined in Swagger""" # noqa: E501 - - self._email = None - self._password = None - self._subdomain = None - self._name = None - self._key = None - self._url = None - self.discriminator = None - - if email is not None: - self.email = email - if password is not None: - self.password = password - self.subdomain = subdomain - if name is not None: - self.name = name - if key is not None: - self.key = key - if url is not None: - self.url = url - - @property - def email(self): - """Gets the email of this AuthToken. # noqa: E501 - - - :return: The email of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._email - - @email.setter - def email(self, email): - """Sets the email of this AuthToken. - - - :param email: The email of this AuthToken. # noqa: E501 - :type: str - """ - - self._email = email - - @property - def password(self): - """Gets the password of this AuthToken. # noqa: E501 - - - :return: The password of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._password - - @password.setter - def password(self, password): - """Sets the password of this AuthToken. - - - :param password: The password of this AuthToken. # noqa: E501 - :type: str - """ - - self._password = password - - @property - def subdomain(self): - """Gets the subdomain of this AuthToken. # noqa: E501 - - - :return: The subdomain of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._subdomain - - @subdomain.setter - def subdomain(self, subdomain): - """Sets the subdomain of this AuthToken. - - - :param subdomain: The subdomain of this AuthToken. # noqa: E501 - :type: str - """ - if subdomain is None: - raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 - if subdomain is not None and len(subdomain) < 1: - raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 - if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 - raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 - - self._subdomain = subdomain - - @property - def name(self): - """Gets the name of this AuthToken. # noqa: E501 - - - :return: The name of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this AuthToken. - - - :param name: The name of this AuthToken. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def key(self): - """Gets the key of this AuthToken. # noqa: E501 - - - :return: The key of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._key - - @key.setter - def key(self, key): - """Sets the key of this AuthToken. - - - :param key: The key of this AuthToken. # noqa: E501 - :type: str - """ - if key is not None and len(key) < 1: - raise ValueError("Invalid value for `key`, length must be greater than or equal to `1`") # noqa: E501 - - self._key = key - - @property - def url(self): - """Gets the url of this AuthToken. # noqa: E501 - - - :return: The url of this AuthToken. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this AuthToken. - - - :param url: The url of this AuthToken. # noqa: E501 - :type: str - """ - - self._url = url - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, AuthToken): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/document.py b/signrequest_python_client/models/document.py deleted file mode 100644 index 1f51ba0..0000000 --- a/signrequest_python_client/models/document.py +++ /dev/null @@ -1,748 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 -from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: F401,E501 -from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 -from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 -from signrequest_python_client.models.user import User # noqa: F401,E501 - - -class Document(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'url': 'str', - 'uuid': 'str', - 'user': 'User', - 'file_as_pdf': 'str', - 'name': 'str', - 'external_id': 'str', - 'frontend_id': 'str', - 'file': 'str', - 'file_from_url': 'str', - 'events_callback_url': 'str', - 'file_from_content': 'str', - 'file_from_content_name': 'str', - 'template': 'str', - 'prefill_tags': 'list[InlinePrefillTags]', - 'integrations': 'list[InlineIntegrationData]', - 'file_from_sf': 'FileFromSf', - 'auto_delete_days': 'int', - 'pdf': 'str', - 'status': 'str', - 'api_used': 'bool', - 'security_hash': 'str', - 'attachments': 'list[DocumentAttachment]', - 'auto_delete_after': 'datetime' - } - - attribute_map = { - 'url': 'url', - 'uuid': 'uuid', - 'user': 'user', - 'file_as_pdf': 'file_as_pdf', - 'name': 'name', - 'external_id': 'external_id', - 'frontend_id': 'frontend_id', - 'file': 'file', - 'file_from_url': 'file_from_url', - 'events_callback_url': 'events_callback_url', - 'file_from_content': 'file_from_content', - 'file_from_content_name': 'file_from_content_name', - 'template': 'template', - 'prefill_tags': 'prefill_tags', - 'integrations': 'integrations', - 'file_from_sf': 'file_from_sf', - 'auto_delete_days': 'auto_delete_days', - 'pdf': 'pdf', - 'status': 'status', - 'api_used': 'api_used', - 'security_hash': 'security_hash', - 'attachments': 'attachments', - 'auto_delete_after': 'auto_delete_after' - } - - def __init__(self, url=None, uuid=None, user=None, file_as_pdf=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None, pdf=None, status=None, api_used=None, security_hash=None, attachments=None, auto_delete_after=None): # noqa: E501 - """Document - a model defined in Swagger""" # noqa: E501 - - self._url = None - self._uuid = None - self._user = None - self._file_as_pdf = None - self._name = None - self._external_id = None - self._frontend_id = None - self._file = None - self._file_from_url = None - self._events_callback_url = None - self._file_from_content = None - self._file_from_content_name = None - self._template = None - self._prefill_tags = None - self._integrations = None - self._file_from_sf = None - self._auto_delete_days = None - self._pdf = None - self._status = None - self._api_used = None - self._security_hash = None - self._attachments = None - self._auto_delete_after = None - self.discriminator = None - - if url is not None: - self.url = url - if uuid is not None: - self.uuid = uuid - if user is not None: - self.user = user - if file_as_pdf is not None: - self.file_as_pdf = file_as_pdf - if name is not None: - self.name = name - if external_id is not None: - self.external_id = external_id - if frontend_id is not None: - self.frontend_id = frontend_id - if file is not None: - self.file = file - if file_from_url is not None: - self.file_from_url = file_from_url - if events_callback_url is not None: - self.events_callback_url = events_callback_url - if file_from_content is not None: - self.file_from_content = file_from_content - if file_from_content_name is not None: - self.file_from_content_name = file_from_content_name - if template is not None: - self.template = template - if prefill_tags is not None: - self.prefill_tags = prefill_tags - if integrations is not None: - self.integrations = integrations - if file_from_sf is not None: - self.file_from_sf = file_from_sf - if auto_delete_days is not None: - self.auto_delete_days = auto_delete_days - if pdf is not None: - self.pdf = pdf - if status is not None: - self.status = status - if api_used is not None: - self.api_used = api_used - if security_hash is not None: - self.security_hash = security_hash - if attachments is not None: - self.attachments = attachments - if auto_delete_after is not None: - self.auto_delete_after = auto_delete_after - - @property - def url(self): - """Gets the url of this Document. # noqa: E501 - - - :return: The url of this Document. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this Document. - - - :param url: The url of this Document. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def uuid(self): - """Gets the uuid of this Document. # noqa: E501 - - - :return: The uuid of this Document. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this Document. - - - :param uuid: The uuid of this Document. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def user(self): - """Gets the user of this Document. # noqa: E501 - - - :return: The user of this Document. # noqa: E501 - :rtype: User - """ - return self._user - - @user.setter - def user(self, user): - """Sets the user of this Document. - - - :param user: The user of this Document. # noqa: E501 - :type: User - """ - - self._user = user - - @property - def file_as_pdf(self): - """Gets the file_as_pdf of this Document. # noqa: E501 - - Temporary URL to original file as PDF, expires in five minutes # noqa: E501 - - :return: The file_as_pdf of this Document. # noqa: E501 - :rtype: str - """ - return self._file_as_pdf - - @file_as_pdf.setter - def file_as_pdf(self, file_as_pdf): - """Sets the file_as_pdf of this Document. - - Temporary URL to original file as PDF, expires in five minutes # noqa: E501 - - :param file_as_pdf: The file_as_pdf of this Document. # noqa: E501 - :type: str - """ - if file_as_pdf is not None and len(file_as_pdf) < 1: - raise ValueError("Invalid value for `file_as_pdf`, length must be greater than or equal to `1`") # noqa: E501 - - self._file_as_pdf = file_as_pdf - - @property - def name(self): - """Gets the name of this Document. # noqa: E501 - - Defaults to filename, including extension # noqa: E501 - - :return: The name of this Document. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this Document. - - Defaults to filename, including extension # noqa: E501 - - :param name: The name of this Document. # noqa: E501 - :type: str - """ - if name is not None and len(name) > 255: - raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 - - self._name = name - - @property - def external_id(self): - """Gets the external_id of this Document. # noqa: E501 - - ID used to reference document in external system # noqa: E501 - - :return: The external_id of this Document. # noqa: E501 - :rtype: str - """ - return self._external_id - - @external_id.setter - def external_id(self, external_id): - """Sets the external_id of this Document. - - ID used to reference document in external system # noqa: E501 - - :param external_id: The external_id of this Document. # noqa: E501 - :type: str - """ - if external_id is not None and len(external_id) > 255: - raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 - - self._external_id = external_id - - @property - def frontend_id(self): - """Gets the frontend_id of this Document. # noqa: E501 - - Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 - - :return: The frontend_id of this Document. # noqa: E501 - :rtype: str - """ - return self._frontend_id - - @frontend_id.setter - def frontend_id(self, frontend_id): - """Sets the frontend_id of this Document. - - Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 - - :param frontend_id: The frontend_id of this Document. # noqa: E501 - :type: str - """ - if frontend_id is not None and len(frontend_id) > 255: - raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 - - self._frontend_id = frontend_id - - @property - def file(self): - """Gets the file of this Document. # noqa: E501 - - Temporary URL to original file, expires in five minutes # noqa: E501 - - :return: The file of this Document. # noqa: E501 - :rtype: str - """ - return self._file - - @file.setter - def file(self, file): - """Sets the file of this Document. - - Temporary URL to original file, expires in five minutes # noqa: E501 - - :param file: The file of this Document. # noqa: E501 - :type: str - """ - - self._file = file - - @property - def file_from_url(self): - """Gets the file_from_url of this Document. # noqa: E501 - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :return: The file_from_url of this Document. # noqa: E501 - :rtype: str - """ - return self._file_from_url - - @file_from_url.setter - def file_from_url(self, file_from_url): - """Sets the file_from_url of this Document. - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :param file_from_url: The file_from_url of this Document. # noqa: E501 - :type: str - """ - if file_from_url is not None and len(file_from_url) > 2100: - raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._file_from_url = file_from_url - - @property - def events_callback_url(self): - """Gets the events_callback_url of this Document. # noqa: E501 - - URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 - - :return: The events_callback_url of this Document. # noqa: E501 - :rtype: str - """ - return self._events_callback_url - - @events_callback_url.setter - def events_callback_url(self, events_callback_url): - """Sets the events_callback_url of this Document. - - URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 - - :param events_callback_url: The events_callback_url of this Document. # noqa: E501 - :type: str - """ - if events_callback_url is not None and len(events_callback_url) > 2100: - raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._events_callback_url = events_callback_url - - @property - def file_from_content(self): - """Gets the file_from_content of this Document. # noqa: E501 - - Base64 encoded document content # noqa: E501 - - :return: The file_from_content of this Document. # noqa: E501 - :rtype: str - """ - return self._file_from_content - - @file_from_content.setter - def file_from_content(self, file_from_content): - """Sets the file_from_content of this Document. - - Base64 encoded document content # noqa: E501 - - :param file_from_content: The file_from_content of this Document. # noqa: E501 - :type: str - """ - - self._file_from_content = file_from_content - - @property - def file_from_content_name(self): - """Gets the file_from_content_name of this Document. # noqa: E501 - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :return: The file_from_content_name of this Document. # noqa: E501 - :rtype: str - """ - return self._file_from_content_name - - @file_from_content_name.setter - def file_from_content_name(self, file_from_content_name): - """Sets the file_from_content_name of this Document. - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :param file_from_content_name: The file_from_content_name of this Document. # noqa: E501 - :type: str - """ - - self._file_from_content_name = file_from_content_name - - @property - def template(self): - """Gets the template of this Document. # noqa: E501 - - - :return: The template of this Document. # noqa: E501 - :rtype: str - """ - return self._template - - @template.setter - def template(self, template): - """Sets the template of this Document. - - - :param template: The template of this Document. # noqa: E501 - :type: str - """ - - self._template = template - - @property - def prefill_tags(self): - """Gets the prefill_tags of this Document. # noqa: E501 - - Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 - - :return: The prefill_tags of this Document. # noqa: E501 - :rtype: list[InlinePrefillTags] - """ - return self._prefill_tags - - @prefill_tags.setter - def prefill_tags(self, prefill_tags): - """Sets the prefill_tags of this Document. - - Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 - - :param prefill_tags: The prefill_tags of this Document. # noqa: E501 - :type: list[InlinePrefillTags] - """ - - self._prefill_tags = prefill_tags - - @property - def integrations(self): - """Gets the integrations of this Document. # noqa: E501 - - - :return: The integrations of this Document. # noqa: E501 - :rtype: list[InlineIntegrationData] - """ - return self._integrations - - @integrations.setter - def integrations(self, integrations): - """Sets the integrations of this Document. - - - :param integrations: The integrations of this Document. # noqa: E501 - :type: list[InlineIntegrationData] - """ - - self._integrations = integrations - - @property - def file_from_sf(self): - """Gets the file_from_sf of this Document. # noqa: E501 - - - :return: The file_from_sf of this Document. # noqa: E501 - :rtype: FileFromSf - """ - return self._file_from_sf - - @file_from_sf.setter - def file_from_sf(self, file_from_sf): - """Sets the file_from_sf of this Document. - - - :param file_from_sf: The file_from_sf of this Document. # noqa: E501 - :type: FileFromSf - """ - - self._file_from_sf = file_from_sf - - @property - def auto_delete_days(self): - """Gets the auto_delete_days of this Document. # noqa: E501 - - Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :return: The auto_delete_days of this Document. # noqa: E501 - :rtype: int - """ - return self._auto_delete_days - - @auto_delete_days.setter - def auto_delete_days(self, auto_delete_days): - """Sets the auto_delete_days of this Document. - - Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :param auto_delete_days: The auto_delete_days of this Document. # noqa: E501 - :type: int - """ - if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 - raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 - if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 - raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 - - self._auto_delete_days = auto_delete_days - - @property - def pdf(self): - """Gets the pdf of this Document. # noqa: E501 - - Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 - - :return: The pdf of this Document. # noqa: E501 - :rtype: str - """ - return self._pdf - - @pdf.setter - def pdf(self, pdf): - """Sets the pdf of this Document. - - Temporary URL to signed document as PDF, expires in five minutes # noqa: E501 - - :param pdf: The pdf of this Document. # noqa: E501 - :type: str - """ - - self._pdf = pdf - - @property - def status(self): - """Gets the status of this Document. # noqa: E501 - - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 - - :return: The status of this Document. # noqa: E501 - :rtype: str - """ - return self._status - - @status.setter - def status(self, status): - """Sets the status of this Document. - - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 - - :param status: The status of this Document. # noqa: E501 - :type: str - """ - allowed_values = ["co", "ne", "se", "vi", "si", "do", "sd", "ca", "de", "ec", "es", "xp"] # noqa: E501 - if status not in allowed_values: - raise ValueError( - "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 - .format(status, allowed_values) - ) - - self._status = status - - @property - def api_used(self): - """Gets the api_used of this Document. # noqa: E501 - - Indicates whether document was created using the API # noqa: E501 - - :return: The api_used of this Document. # noqa: E501 - :rtype: bool - """ - return self._api_used - - @api_used.setter - def api_used(self, api_used): - """Sets the api_used of this Document. - - Indicates whether document was created using the API # noqa: E501 - - :param api_used: The api_used of this Document. # noqa: E501 - :type: bool - """ - - self._api_used = api_used - - @property - def security_hash(self): - """Gets the security_hash of this Document. # noqa: E501 - - SHA256 hash of PDF contents # noqa: E501 - - :return: The security_hash of this Document. # noqa: E501 - :rtype: str - """ - return self._security_hash - - @security_hash.setter - def security_hash(self, security_hash): - """Sets the security_hash of this Document. - - SHA256 hash of PDF contents # noqa: E501 - - :param security_hash: The security_hash of this Document. # noqa: E501 - :type: str - """ - if security_hash is not None and len(security_hash) < 1: - raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 - - self._security_hash = security_hash - - @property - def attachments(self): - """Gets the attachments of this Document. # noqa: E501 - - - :return: The attachments of this Document. # noqa: E501 - :rtype: list[DocumentAttachment] - """ - return self._attachments - - @attachments.setter - def attachments(self, attachments): - """Sets the attachments of this Document. - - - :param attachments: The attachments of this Document. # noqa: E501 - :type: list[DocumentAttachment] - """ - - self._attachments = attachments - - @property - def auto_delete_after(self): - """Gets the auto_delete_after of this Document. # noqa: E501 - - Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :return: The auto_delete_after of this Document. # noqa: E501 - :rtype: datetime - """ - return self._auto_delete_after - - @auto_delete_after.setter - def auto_delete_after(self, auto_delete_after): - """Sets the auto_delete_after of this Document. - - Date and time calculated using `auto_delete_days` after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :param auto_delete_after: The auto_delete_after of this Document. # noqa: E501 - :type: datetime - """ - - self._auto_delete_after = auto_delete_after - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Document): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/document_attachment.py b/signrequest_python_client/models/document_attachment.py deleted file mode 100644 index 198b560..0000000 --- a/signrequest_python_client/models/document_attachment.py +++ /dev/null @@ -1,311 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class DocumentAttachment(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'url': 'str', - 'uuid': 'str', - 'name': 'str', - 'file': 'str', - 'file_from_content': 'str', - 'file_from_content_name': 'str', - 'file_from_url': 'str', - 'document': 'str' - } - - attribute_map = { - 'url': 'url', - 'uuid': 'uuid', - 'name': 'name', - 'file': 'file', - 'file_from_content': 'file_from_content', - 'file_from_content_name': 'file_from_content_name', - 'file_from_url': 'file_from_url', - 'document': 'document' - } - - def __init__(self, url=None, uuid=None, name=None, file=None, file_from_content=None, file_from_content_name=None, file_from_url=None, document=None): # noqa: E501 - """DocumentAttachment - a model defined in Swagger""" # noqa: E501 - - self._url = None - self._uuid = None - self._name = None - self._file = None - self._file_from_content = None - self._file_from_content_name = None - self._file_from_url = None - self._document = None - self.discriminator = None - - if url is not None: - self.url = url - if uuid is not None: - self.uuid = uuid - if name is not None: - self.name = name - if file is not None: - self.file = file - if file_from_content is not None: - self.file_from_content = file_from_content - if file_from_content_name is not None: - self.file_from_content_name = file_from_content_name - if file_from_url is not None: - self.file_from_url = file_from_url - self.document = document - - @property - def url(self): - """Gets the url of this DocumentAttachment. # noqa: E501 - - - :return: The url of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this DocumentAttachment. - - - :param url: The url of this DocumentAttachment. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def uuid(self): - """Gets the uuid of this DocumentAttachment. # noqa: E501 - - - :return: The uuid of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this DocumentAttachment. - - - :param uuid: The uuid of this DocumentAttachment. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def name(self): - """Gets the name of this DocumentAttachment. # noqa: E501 - - Defaults to filename # noqa: E501 - - :return: The name of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this DocumentAttachment. - - Defaults to filename # noqa: E501 - - :param name: The name of this DocumentAttachment. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def file(self): - """Gets the file of this DocumentAttachment. # noqa: E501 - - Temporary URL to document attachment, expires in five minutes # noqa: E501 - - :return: The file of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._file - - @file.setter - def file(self, file): - """Sets the file of this DocumentAttachment. - - Temporary URL to document attachment, expires in five minutes # noqa: E501 - - :param file: The file of this DocumentAttachment. # noqa: E501 - :type: str - """ - - self._file = file - - @property - def file_from_content(self): - """Gets the file_from_content of this DocumentAttachment. # noqa: E501 - - Base64 encoded document content # noqa: E501 - - :return: The file_from_content of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._file_from_content - - @file_from_content.setter - def file_from_content(self, file_from_content): - """Sets the file_from_content of this DocumentAttachment. - - Base64 encoded document content # noqa: E501 - - :param file_from_content: The file_from_content of this DocumentAttachment. # noqa: E501 - :type: str - """ - - self._file_from_content = file_from_content - - @property - def file_from_content_name(self): - """Gets the file_from_content_name of this DocumentAttachment. # noqa: E501 - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :return: The file_from_content_name of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._file_from_content_name - - @file_from_content_name.setter - def file_from_content_name(self, file_from_content_name): - """Sets the file_from_content_name of this DocumentAttachment. - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :param file_from_content_name: The file_from_content_name of this DocumentAttachment. # noqa: E501 - :type: str - """ - - self._file_from_content_name = file_from_content_name - - @property - def file_from_url(self): - """Gets the file_from_url of this DocumentAttachment. # noqa: E501 - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :return: The file_from_url of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._file_from_url - - @file_from_url.setter - def file_from_url(self, file_from_url): - """Sets the file_from_url of this DocumentAttachment. - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :param file_from_url: The file_from_url of this DocumentAttachment. # noqa: E501 - :type: str - """ - if file_from_url is not None and len(file_from_url) > 2100: - raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._file_from_url = file_from_url - - @property - def document(self): - """Gets the document of this DocumentAttachment. # noqa: E501 - - - :return: The document of this DocumentAttachment. # noqa: E501 - :rtype: str - """ - return self._document - - @document.setter - def document(self, document): - """Sets the document of this DocumentAttachment. - - - :param document: The document of this DocumentAttachment. # noqa: E501 - :type: str - """ - if document is None: - raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 - - self._document = document - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, DocumentAttachment): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/document_search.py b/signrequest_python_client/models/document_search.py deleted file mode 100644 index cfb5421..0000000 --- a/signrequest_python_client/models/document_search.py +++ /dev/null @@ -1,504 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class DocumentSearch(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'status': 'str', - 'name': 'str', - 'who': 'str', - 'nr_extra_docs': 'int', - 'from_email': 'str', - 'uuid': 'str', - 'created': 'datetime', - 'autocomplete': 'str', - 'signer_emails': 'list[str]', - 'status_display': 'str', - 'created_timestamp': 'int', - 'finished_on_timestamp': 'int', - 'parent_doc': 'str', - 'finished_on': 'datetime', - 'subdomain': 'str' - } - - attribute_map = { - 'status': 'status', - 'name': 'name', - 'who': 'who', - 'nr_extra_docs': 'nr_extra_docs', - 'from_email': 'from_email', - 'uuid': 'uuid', - 'created': 'created', - 'autocomplete': 'autocomplete', - 'signer_emails': 'signer_emails', - 'status_display': 'status_display', - 'created_timestamp': 'created_timestamp', - 'finished_on_timestamp': 'finished_on_timestamp', - 'parent_doc': 'parent_doc', - 'finished_on': 'finished_on', - 'subdomain': 'subdomain' - } - - def __init__(self, status=None, name=None, who=None, nr_extra_docs=None, from_email=None, uuid=None, created=None, autocomplete=None, signer_emails=None, status_display=None, created_timestamp=None, finished_on_timestamp=None, parent_doc=None, finished_on=None, subdomain=None): # noqa: E501 - """DocumentSearch - a model defined in Swagger""" # noqa: E501 - - self._status = None - self._name = None - self._who = None - self._nr_extra_docs = None - self._from_email = None - self._uuid = None - self._created = None - self._autocomplete = None - self._signer_emails = None - self._status_display = None - self._created_timestamp = None - self._finished_on_timestamp = None - self._parent_doc = None - self._finished_on = None - self._subdomain = None - self.discriminator = None - - if status is not None: - self.status = status - if name is not None: - self.name = name - self.who = who - self.nr_extra_docs = nr_extra_docs - self.from_email = from_email - if uuid is not None: - self.uuid = uuid - if created is not None: - self.created = created - self.autocomplete = autocomplete - if signer_emails is not None: - self.signer_emails = signer_emails - if status_display is not None: - self.status_display = status_display - if created_timestamp is not None: - self.created_timestamp = created_timestamp - if finished_on_timestamp is not None: - self.finished_on_timestamp = finished_on_timestamp - if parent_doc is not None: - self.parent_doc = parent_doc - if finished_on is not None: - self.finished_on = finished_on - if subdomain is not None: - self.subdomain = subdomain - - @property - def status(self): - """Gets the status of this DocumentSearch. # noqa: E501 - - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 - - :return: The status of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._status - - @status.setter - def status(self, status): - """Sets the status of this DocumentSearch. - - `co`: converting, `ne`: new, `se`: sent, `vi`: viewed, `si`: signed, `do`: downloaded, `sd`: signed and downloaded, `ca`: cancelled, `de`: declined, `ec`: error converting, `es`: error sending, `xp`: expired # noqa: E501 - - :param status: The status of this DocumentSearch. # noqa: E501 - :type: str - """ - if status is not None and len(status) > 2: - raise ValueError("Invalid value for `status`, length must be less than or equal to `2`") # noqa: E501 - if status is not None and len(status) < 1: - raise ValueError("Invalid value for `status`, length must be greater than or equal to `1`") # noqa: E501 - - self._status = status - - @property - def name(self): - """Gets the name of this DocumentSearch. # noqa: E501 - - Defaults to filename # noqa: E501 - - :return: The name of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this DocumentSearch. - - Defaults to filename # noqa: E501 - - :param name: The name of this DocumentSearch. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def who(self): - """Gets the who of this DocumentSearch. # noqa: E501 - - - :return: The who of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._who - - @who.setter - def who(self, who): - """Sets the who of this DocumentSearch. - - - :param who: The who of this DocumentSearch. # noqa: E501 - :type: str - """ - if who is None: - raise ValueError("Invalid value for `who`, must not be `None`") # noqa: E501 - if who is not None and len(who) < 1: - raise ValueError("Invalid value for `who`, length must be greater than or equal to `1`") # noqa: E501 - - self._who = who - - @property - def nr_extra_docs(self): - """Gets the nr_extra_docs of this DocumentSearch. # noqa: E501 - - - :return: The nr_extra_docs of this DocumentSearch. # noqa: E501 - :rtype: int - """ - return self._nr_extra_docs - - @nr_extra_docs.setter - def nr_extra_docs(self, nr_extra_docs): - """Sets the nr_extra_docs of this DocumentSearch. - - - :param nr_extra_docs: The nr_extra_docs of this DocumentSearch. # noqa: E501 - :type: int - """ - if nr_extra_docs is None: - raise ValueError("Invalid value for `nr_extra_docs`, must not be `None`") # noqa: E501 - - self._nr_extra_docs = nr_extra_docs - - @property - def from_email(self): - """Gets the from_email of this DocumentSearch. # noqa: E501 - - - :return: The from_email of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._from_email - - @from_email.setter - def from_email(self, from_email): - """Sets the from_email of this DocumentSearch. - - - :param from_email: The from_email of this DocumentSearch. # noqa: E501 - :type: str - """ - if from_email is None: - raise ValueError("Invalid value for `from_email`, must not be `None`") # noqa: E501 - if from_email is not None and len(from_email) < 1: - raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 - - self._from_email = from_email - - @property - def uuid(self): - """Gets the uuid of this DocumentSearch. # noqa: E501 - - - :return: The uuid of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this DocumentSearch. - - - :param uuid: The uuid of this DocumentSearch. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def created(self): - """Gets the created of this DocumentSearch. # noqa: E501 - - - :return: The created of this DocumentSearch. # noqa: E501 - :rtype: datetime - """ - return self._created - - @created.setter - def created(self, created): - """Sets the created of this DocumentSearch. - - - :param created: The created of this DocumentSearch. # noqa: E501 - :type: datetime - """ - - self._created = created - - @property - def autocomplete(self): - """Gets the autocomplete of this DocumentSearch. # noqa: E501 - - - :return: The autocomplete of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._autocomplete - - @autocomplete.setter - def autocomplete(self, autocomplete): - """Sets the autocomplete of this DocumentSearch. - - - :param autocomplete: The autocomplete of this DocumentSearch. # noqa: E501 - :type: str - """ - if autocomplete is None: - raise ValueError("Invalid value for `autocomplete`, must not be `None`") # noqa: E501 - if autocomplete is not None and len(autocomplete) < 1: - raise ValueError("Invalid value for `autocomplete`, length must be greater than or equal to `1`") # noqa: E501 - - self._autocomplete = autocomplete - - @property - def signer_emails(self): - """Gets the signer_emails of this DocumentSearch. # noqa: E501 - - - :return: The signer_emails of this DocumentSearch. # noqa: E501 - :rtype: list[str] - """ - return self._signer_emails - - @signer_emails.setter - def signer_emails(self, signer_emails): - """Sets the signer_emails of this DocumentSearch. - - - :param signer_emails: The signer_emails of this DocumentSearch. # noqa: E501 - :type: list[str] - """ - - self._signer_emails = signer_emails - - @property - def status_display(self): - """Gets the status_display of this DocumentSearch. # noqa: E501 - - - :return: The status_display of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._status_display - - @status_display.setter - def status_display(self, status_display): - """Sets the status_display of this DocumentSearch. - - - :param status_display: The status_display of this DocumentSearch. # noqa: E501 - :type: str - """ - if status_display is not None and len(status_display) < 1: - raise ValueError("Invalid value for `status_display`, length must be greater than or equal to `1`") # noqa: E501 - - self._status_display = status_display - - @property - def created_timestamp(self): - """Gets the created_timestamp of this DocumentSearch. # noqa: E501 - - - :return: The created_timestamp of this DocumentSearch. # noqa: E501 - :rtype: int - """ - return self._created_timestamp - - @created_timestamp.setter - def created_timestamp(self, created_timestamp): - """Sets the created_timestamp of this DocumentSearch. - - - :param created_timestamp: The created_timestamp of this DocumentSearch. # noqa: E501 - :type: int - """ - - self._created_timestamp = created_timestamp - - @property - def finished_on_timestamp(self): - """Gets the finished_on_timestamp of this DocumentSearch. # noqa: E501 - - - :return: The finished_on_timestamp of this DocumentSearch. # noqa: E501 - :rtype: int - """ - return self._finished_on_timestamp - - @finished_on_timestamp.setter - def finished_on_timestamp(self, finished_on_timestamp): - """Sets the finished_on_timestamp of this DocumentSearch. - - - :param finished_on_timestamp: The finished_on_timestamp of this DocumentSearch. # noqa: E501 - :type: int - """ - - self._finished_on_timestamp = finished_on_timestamp - - @property - def parent_doc(self): - """Gets the parent_doc of this DocumentSearch. # noqa: E501 - - - :return: The parent_doc of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._parent_doc - - @parent_doc.setter - def parent_doc(self, parent_doc): - """Sets the parent_doc of this DocumentSearch. - - - :param parent_doc: The parent_doc of this DocumentSearch. # noqa: E501 - :type: str - """ - if parent_doc is not None and len(parent_doc) < 1: - raise ValueError("Invalid value for `parent_doc`, length must be greater than or equal to `1`") # noqa: E501 - - self._parent_doc = parent_doc - - @property - def finished_on(self): - """Gets the finished_on of this DocumentSearch. # noqa: E501 - - - :return: The finished_on of this DocumentSearch. # noqa: E501 - :rtype: datetime - """ - return self._finished_on - - @finished_on.setter - def finished_on(self, finished_on): - """Sets the finished_on of this DocumentSearch. - - - :param finished_on: The finished_on of this DocumentSearch. # noqa: E501 - :type: datetime - """ - - self._finished_on = finished_on - - @property - def subdomain(self): - """Gets the subdomain of this DocumentSearch. # noqa: E501 - - - :return: The subdomain of this DocumentSearch. # noqa: E501 - :rtype: str - """ - return self._subdomain - - @subdomain.setter - def subdomain(self, subdomain): - """Sets the subdomain of this DocumentSearch. - - - :param subdomain: The subdomain of this DocumentSearch. # noqa: E501 - :type: str - """ - if subdomain is not None and len(subdomain) < 1: - raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 - - self._subdomain = subdomain - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, DocumentSearch): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/document_signer_template_conf.py b/signrequest_python_client/models/document_signer_template_conf.py deleted file mode 100644 index c9a6ee1..0000000 --- a/signrequest_python_client/models/document_signer_template_conf.py +++ /dev/null @@ -1,278 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.placeholder import Placeholder # noqa: F401,E501 - - -class DocumentSignerTemplateConf(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'signer_index': 'int', - 'needs_to_sign': 'bool', - 'approve_only': 'bool', - 'notify_only': 'bool', - 'in_person': 'bool', - 'order': 'int', - 'placeholders': 'list[Placeholder]' - } - - attribute_map = { - 'signer_index': 'signer_index', - 'needs_to_sign': 'needs_to_sign', - 'approve_only': 'approve_only', - 'notify_only': 'notify_only', - 'in_person': 'in_person', - 'order': 'order', - 'placeholders': 'placeholders' - } - - def __init__(self, signer_index=None, needs_to_sign=None, approve_only=None, notify_only=None, in_person=None, order=None, placeholders=None): # noqa: E501 - """DocumentSignerTemplateConf - a model defined in Swagger""" # noqa: E501 - - self._signer_index = None - self._needs_to_sign = None - self._approve_only = None - self._notify_only = None - self._in_person = None - self._order = None - self._placeholders = None - self.discriminator = None - - if signer_index is not None: - self.signer_index = signer_index - if needs_to_sign is not None: - self.needs_to_sign = needs_to_sign - if approve_only is not None: - self.approve_only = approve_only - if notify_only is not None: - self.notify_only = notify_only - if in_person is not None: - self.in_person = in_person - if order is not None: - self.order = order - if placeholders is not None: - self.placeholders = placeholders - - @property - def signer_index(self): - """Gets the signer_index of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: int - """ - return self._signer_index - - @signer_index.setter - def signer_index(self, signer_index): - """Sets the signer_index of this DocumentSignerTemplateConf. - - - :param signer_index: The signer_index of this DocumentSignerTemplateConf. # noqa: E501 - :type: int - """ - if signer_index is not None and signer_index > 2147483647: # noqa: E501 - raise ValueError("Invalid value for `signer_index`, must be a value less than or equal to `2147483647`") # noqa: E501 - if signer_index is not None and signer_index < -2147483648: # noqa: E501 - raise ValueError("Invalid value for `signer_index`, must be a value greater than or equal to `-2147483648`") # noqa: E501 - - self._signer_index = signer_index - - @property - def needs_to_sign(self): - """Gets the needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: bool - """ - return self._needs_to_sign - - @needs_to_sign.setter - def needs_to_sign(self, needs_to_sign): - """Sets the needs_to_sign of this DocumentSignerTemplateConf. - - - :param needs_to_sign: The needs_to_sign of this DocumentSignerTemplateConf. # noqa: E501 - :type: bool - """ - - self._needs_to_sign = needs_to_sign - - @property - def approve_only(self): - """Gets the approve_only of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: bool - """ - return self._approve_only - - @approve_only.setter - def approve_only(self, approve_only): - """Sets the approve_only of this DocumentSignerTemplateConf. - - - :param approve_only: The approve_only of this DocumentSignerTemplateConf. # noqa: E501 - :type: bool - """ - - self._approve_only = approve_only - - @property - def notify_only(self): - """Gets the notify_only of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: bool - """ - return self._notify_only - - @notify_only.setter - def notify_only(self, notify_only): - """Sets the notify_only of this DocumentSignerTemplateConf. - - - :param notify_only: The notify_only of this DocumentSignerTemplateConf. # noqa: E501 - :type: bool - """ - - self._notify_only = notify_only - - @property - def in_person(self): - """Gets the in_person of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The in_person of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: bool - """ - return self._in_person - - @in_person.setter - def in_person(self, in_person): - """Sets the in_person of this DocumentSignerTemplateConf. - - - :param in_person: The in_person of this DocumentSignerTemplateConf. # noqa: E501 - :type: bool - """ - - self._in_person = in_person - - @property - def order(self): - """Gets the order of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The order of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: int - """ - return self._order - - @order.setter - def order(self, order): - """Sets the order of this DocumentSignerTemplateConf. - - - :param order: The order of this DocumentSignerTemplateConf. # noqa: E501 - :type: int - """ - if order is not None and order > 2147483647: # noqa: E501 - raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 - if order is not None and order < 0: # noqa: E501 - raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 - - self._order = order - - @property - def placeholders(self): - """Gets the placeholders of this DocumentSignerTemplateConf. # noqa: E501 - - - :return: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 - :rtype: list[Placeholder] - """ - return self._placeholders - - @placeholders.setter - def placeholders(self, placeholders): - """Sets the placeholders of this DocumentSignerTemplateConf. - - - :param placeholders: The placeholders of this DocumentSignerTemplateConf. # noqa: E501 - :type: list[Placeholder] - """ - - self._placeholders = placeholders - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, DocumentSignerTemplateConf): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/event.py b/signrequest_python_client/models/event.py deleted file mode 100644 index ef7cfb6..0000000 --- a/signrequest_python_client/models/event.py +++ /dev/null @@ -1,337 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document import Document # noqa: F401,E501 -from signrequest_python_client.models.signer import Signer # noqa: F401,E501 - - -class Event(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'uuid': 'str', - 'status': 'str', - 'event_type': 'str', - 'delivered': 'bool', - 'delivered_on': 'datetime', - 'callback_status_code': 'int', - 'timestamp': 'datetime', - 'document': 'Document', - 'signer': 'Signer' - } - - attribute_map = { - 'uuid': 'uuid', - 'status': 'status', - 'event_type': 'event_type', - 'delivered': 'delivered', - 'delivered_on': 'delivered_on', - 'callback_status_code': 'callback_status_code', - 'timestamp': 'timestamp', - 'document': 'document', - 'signer': 'signer' - } - - def __init__(self, uuid=None, status=None, event_type=None, delivered=None, delivered_on=None, callback_status_code=None, timestamp=None, document=None, signer=None): # noqa: E501 - """Event - a model defined in Swagger""" # noqa: E501 - - self._uuid = None - self._status = None - self._event_type = None - self._delivered = None - self._delivered_on = None - self._callback_status_code = None - self._timestamp = None - self._document = None - self._signer = None - self.discriminator = None - - if uuid is not None: - self.uuid = uuid - if status is not None: - self.status = status - if event_type is not None: - self.event_type = event_type - if delivered is not None: - self.delivered = delivered - if delivered_on is not None: - self.delivered_on = delivered_on - if callback_status_code is not None: - self.callback_status_code = callback_status_code - if timestamp is not None: - self.timestamp = timestamp - if document is not None: - self.document = document - if signer is not None: - self.signer = signer - - @property - def uuid(self): - """Gets the uuid of this Event. # noqa: E501 - - - :return: The uuid of this Event. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this Event. - - - :param uuid: The uuid of this Event. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def status(self): - """Gets the status of this Event. # noqa: E501 - - - :return: The status of this Event. # noqa: E501 - :rtype: str - """ - return self._status - - @status.setter - def status(self, status): - """Sets the status of this Event. - - - :param status: The status of this Event. # noqa: E501 - :type: str - """ - allowed_values = ["ok", "error"] # noqa: E501 - if status not in allowed_values: - raise ValueError( - "Invalid value for `status` ({0}), must be one of {1}" # noqa: E501 - .format(status, allowed_values) - ) - - self._status = status - - @property - def event_type(self): - """Gets the event_type of this Event. # noqa: E501 - - - :return: The event_type of this Event. # noqa: E501 - :rtype: str - """ - return self._event_type - - @event_type.setter - def event_type(self, event_type): - """Sets the event_type of this Event. - - - :param event_type: The event_type of this Event. # noqa: E501 - :type: str - """ - allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 - if event_type not in allowed_values: - raise ValueError( - "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 - .format(event_type, allowed_values) - ) - - self._event_type = event_type - - @property - def delivered(self): - """Gets the delivered of this Event. # noqa: E501 - - - :return: The delivered of this Event. # noqa: E501 - :rtype: bool - """ - return self._delivered - - @delivered.setter - def delivered(self, delivered): - """Sets the delivered of this Event. - - - :param delivered: The delivered of this Event. # noqa: E501 - :type: bool - """ - - self._delivered = delivered - - @property - def delivered_on(self): - """Gets the delivered_on of this Event. # noqa: E501 - - - :return: The delivered_on of this Event. # noqa: E501 - :rtype: datetime - """ - return self._delivered_on - - @delivered_on.setter - def delivered_on(self, delivered_on): - """Sets the delivered_on of this Event. - - - :param delivered_on: The delivered_on of this Event. # noqa: E501 - :type: datetime - """ - - self._delivered_on = delivered_on - - @property - def callback_status_code(self): - """Gets the callback_status_code of this Event. # noqa: E501 - - - :return: The callback_status_code of this Event. # noqa: E501 - :rtype: int - """ - return self._callback_status_code - - @callback_status_code.setter - def callback_status_code(self, callback_status_code): - """Sets the callback_status_code of this Event. - - - :param callback_status_code: The callback_status_code of this Event. # noqa: E501 - :type: int - """ - - self._callback_status_code = callback_status_code - - @property - def timestamp(self): - """Gets the timestamp of this Event. # noqa: E501 - - - :return: The timestamp of this Event. # noqa: E501 - :rtype: datetime - """ - return self._timestamp - - @timestamp.setter - def timestamp(self, timestamp): - """Sets the timestamp of this Event. - - - :param timestamp: The timestamp of this Event. # noqa: E501 - :type: datetime - """ - - self._timestamp = timestamp - - @property - def document(self): - """Gets the document of this Event. # noqa: E501 - - - :return: The document of this Event. # noqa: E501 - :rtype: Document - """ - return self._document - - @document.setter - def document(self, document): - """Sets the document of this Event. - - - :param document: The document of this Event. # noqa: E501 - :type: Document - """ - - self._document = document - - @property - def signer(self): - """Gets the signer of this Event. # noqa: E501 - - - :return: The signer of this Event. # noqa: E501 - :rtype: Signer - """ - return self._signer - - @signer.setter - def signer(self, signer): - """Sets the signer of this Event. - - - :param signer: The signer of this Event. # noqa: E501 - :type: Signer - """ - - self._signer = signer - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Event): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/file_from_sf.py b/signrequest_python_client/models/file_from_sf.py deleted file mode 100644 index 987c0b2..0000000 --- a/signrequest_python_client/models/file_from_sf.py +++ /dev/null @@ -1,144 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class FileFromSf(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'object_type': 'str', - 'object_id': 'str' - } - - attribute_map = { - 'object_type': 'object_type', - 'object_id': 'object_id' - } - - def __init__(self, object_type=None, object_id=None): # noqa: E501 - """FileFromSf - a model defined in Swagger""" # noqa: E501 - - self._object_type = None - self._object_id = None - self.discriminator = None - - self.object_type = object_type - self.object_id = object_id - - @property - def object_type(self): - """Gets the object_type of this FileFromSf. # noqa: E501 - - - :return: The object_type of this FileFromSf. # noqa: E501 - :rtype: str - """ - return self._object_type - - @object_type.setter - def object_type(self, object_type): - """Sets the object_type of this FileFromSf. - - - :param object_type: The object_type of this FileFromSf. # noqa: E501 - :type: str - """ - if object_type is None: - raise ValueError("Invalid value for `object_type`, must not be `None`") # noqa: E501 - if object_type is not None and len(object_type) < 1: - raise ValueError("Invalid value for `object_type`, length must be greater than or equal to `1`") # noqa: E501 - - self._object_type = object_type - - @property - def object_id(self): - """Gets the object_id of this FileFromSf. # noqa: E501 - - - :return: The object_id of this FileFromSf. # noqa: E501 - :rtype: str - """ - return self._object_id - - @object_id.setter - def object_id(self, object_id): - """Sets the object_id of this FileFromSf. - - - :param object_id: The object_id of this FileFromSf. # noqa: E501 - :type: str - """ - if object_id is None: - raise ValueError("Invalid value for `object_id`, must not be `None`") # noqa: E501 - if object_id is not None and len(object_id) < 1: - raise ValueError("Invalid value for `object_id`, length must be greater than or equal to `1`") # noqa: E501 - - self._object_id = object_id - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, FileFromSf): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_document_signer_integration_data.py b/signrequest_python_client/models/inline_document_signer_integration_data.py deleted file mode 100644 index 9a4c942..0000000 --- a/signrequest_python_client/models/inline_document_signer_integration_data.py +++ /dev/null @@ -1,144 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlineDocumentSignerIntegrationData(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'integration': 'str', - 'integration_data': 'str' - } - - attribute_map = { - 'integration': 'integration', - 'integration_data': 'integration_data' - } - - def __init__(self, integration=None, integration_data=None): # noqa: E501 - """InlineDocumentSignerIntegrationData - a model defined in Swagger""" # noqa: E501 - - self._integration = None - self._integration_data = None - self.discriminator = None - - if integration is not None: - self.integration = integration - if integration_data is not None: - self.integration_data = integration_data - - @property - def integration(self): - """Gets the integration of this InlineDocumentSignerIntegrationData. # noqa: E501 - - - :return: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 - :rtype: str - """ - return self._integration - - @integration.setter - def integration(self, integration): - """Sets the integration of this InlineDocumentSignerIntegrationData. - - - :param integration: The integration of this InlineDocumentSignerIntegrationData. # noqa: E501 - :type: str - """ - allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 - if integration not in allowed_values: - raise ValueError( - "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 - .format(integration, allowed_values) - ) - - self._integration = integration - - @property - def integration_data(self): - """Gets the integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 - - - :return: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 - :rtype: str - """ - return self._integration_data - - @integration_data.setter - def integration_data(self, integration_data): - """Sets the integration_data of this InlineDocumentSignerIntegrationData. - - - :param integration_data: The integration_data of this InlineDocumentSignerIntegrationData. # noqa: E501 - :type: str - """ - - self._integration_data = integration_data - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineDocumentSignerIntegrationData): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_integration_data.py b/signrequest_python_client/models/inline_integration_data.py deleted file mode 100644 index be4a6e8..0000000 --- a/signrequest_python_client/models/inline_integration_data.py +++ /dev/null @@ -1,144 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlineIntegrationData(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'integration': 'str', - 'integration_data': 'str' - } - - attribute_map = { - 'integration': 'integration', - 'integration_data': 'integration_data' - } - - def __init__(self, integration=None, integration_data=None): # noqa: E501 - """InlineIntegrationData - a model defined in Swagger""" # noqa: E501 - - self._integration = None - self._integration_data = None - self.discriminator = None - - if integration is not None: - self.integration = integration - if integration_data is not None: - self.integration_data = integration_data - - @property - def integration(self): - """Gets the integration of this InlineIntegrationData. # noqa: E501 - - - :return: The integration of this InlineIntegrationData. # noqa: E501 - :rtype: str - """ - return self._integration - - @integration.setter - def integration(self, integration): - """Sets the integration of this InlineIntegrationData. - - - :param integration: The integration of this InlineIntegrationData. # noqa: E501 - :type: str - """ - allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 - if integration not in allowed_values: - raise ValueError( - "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 - .format(integration, allowed_values) - ) - - self._integration = integration - - @property - def integration_data(self): - """Gets the integration_data of this InlineIntegrationData. # noqa: E501 - - - :return: The integration_data of this InlineIntegrationData. # noqa: E501 - :rtype: str - """ - return self._integration_data - - @integration_data.setter - def integration_data(self, integration_data): - """Sets the integration_data of this InlineIntegrationData. - - - :param integration_data: The integration_data of this InlineIntegrationData. # noqa: E501 - :type: str - """ - - self._integration_data = integration_data - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineIntegrationData): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_prefill_tags.py b/signrequest_python_client/models/inline_prefill_tags.py deleted file mode 100644 index 9d5b817..0000000 --- a/signrequest_python_client/models/inline_prefill_tags.py +++ /dev/null @@ -1,192 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlinePrefillTags(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'external_id': 'str', - 'text': 'str', - 'checkbox_value': 'bool', - 'date_value': 'date' - } - - attribute_map = { - 'external_id': 'external_id', - 'text': 'text', - 'checkbox_value': 'checkbox_value', - 'date_value': 'date_value' - } - - def __init__(self, external_id=None, text=None, checkbox_value=None, date_value=None): # noqa: E501 - """InlinePrefillTags - a model defined in Swagger""" # noqa: E501 - - self._external_id = None - self._text = None - self._checkbox_value = None - self._date_value = None - self.discriminator = None - - if external_id is not None: - self.external_id = external_id - if text is not None: - self.text = text - if checkbox_value is not None: - self.checkbox_value = checkbox_value - if date_value is not None: - self.date_value = date_value - - @property - def external_id(self): - """Gets the external_id of this InlinePrefillTags. # noqa: E501 - - - :return: The external_id of this InlinePrefillTags. # noqa: E501 - :rtype: str - """ - return self._external_id - - @external_id.setter - def external_id(self, external_id): - """Sets the external_id of this InlinePrefillTags. - - - :param external_id: The external_id of this InlinePrefillTags. # noqa: E501 - :type: str - """ - if external_id is not None and len(external_id) > 255: - raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 - - self._external_id = external_id - - @property - def text(self): - """Gets the text of this InlinePrefillTags. # noqa: E501 - - - :return: The text of this InlinePrefillTags. # noqa: E501 - :rtype: str - """ - return self._text - - @text.setter - def text(self, text): - """Sets the text of this InlinePrefillTags. - - - :param text: The text of this InlinePrefillTags. # noqa: E501 - :type: str - """ - - self._text = text - - @property - def checkbox_value(self): - """Gets the checkbox_value of this InlinePrefillTags. # noqa: E501 - - - :return: The checkbox_value of this InlinePrefillTags. # noqa: E501 - :rtype: bool - """ - return self._checkbox_value - - @checkbox_value.setter - def checkbox_value(self, checkbox_value): - """Sets the checkbox_value of this InlinePrefillTags. - - - :param checkbox_value: The checkbox_value of this InlinePrefillTags. # noqa: E501 - :type: bool - """ - - self._checkbox_value = checkbox_value - - @property - def date_value(self): - """Gets the date_value of this InlinePrefillTags. # noqa: E501 - - - :return: The date_value of this InlinePrefillTags. # noqa: E501 - :rtype: date - """ - return self._date_value - - @date_value.setter - def date_value(self, date_value): - """Sets the date_value of this InlinePrefillTags. - - - :param date_value: The date_value of this InlinePrefillTags. # noqa: E501 - :type: date - """ - - self._date_value = date_value - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlinePrefillTags): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200.py b/signrequest_python_client/models/inline_response_200.py deleted file mode 100644 index 44b847a..0000000 --- a/signrequest_python_client/models/inline_response_200.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.auth_token import AuthToken # noqa: F401,E501 - - -class InlineResponse200(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[AuthToken]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse200 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse200. # noqa: E501 - - - :return: The count of this InlineResponse200. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse200. - - - :param count: The count of this InlineResponse200. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse200. # noqa: E501 - - - :return: The next of this InlineResponse200. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse200. - - - :param next: The next of this InlineResponse200. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse200. # noqa: E501 - - - :return: The previous of this InlineResponse200. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse200. - - - :param previous: The previous of this InlineResponse200. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse200. # noqa: E501 - - - :return: The results of this InlineResponse200. # noqa: E501 - :rtype: list[AuthToken] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse200. - - - :param results: The results of this InlineResponse200. # noqa: E501 - :type: list[AuthToken] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse200): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_1.py b/signrequest_python_client/models/inline_response_200_1.py deleted file mode 100644 index 10e4606..0000000 --- a/signrequest_python_client/models/inline_response_200_1.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document_attachment import DocumentAttachment # noqa: F401,E501 - - -class InlineResponse2001(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[DocumentAttachment]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2001 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2001. # noqa: E501 - - - :return: The count of this InlineResponse2001. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2001. - - - :param count: The count of this InlineResponse2001. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2001. # noqa: E501 - - - :return: The next of this InlineResponse2001. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2001. - - - :param next: The next of this InlineResponse2001. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2001. # noqa: E501 - - - :return: The previous of this InlineResponse2001. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2001. - - - :param previous: The previous of this InlineResponse2001. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2001. # noqa: E501 - - - :return: The results of this InlineResponse2001. # noqa: E501 - :rtype: list[DocumentAttachment] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2001. - - - :param results: The results of this InlineResponse2001. # noqa: E501 - :type: list[DocumentAttachment] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2001): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_2.py b/signrequest_python_client/models/inline_response_200_2.py deleted file mode 100644 index 748c3af..0000000 --- a/signrequest_python_client/models/inline_response_200_2.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document_search import DocumentSearch # noqa: F401,E501 - - -class InlineResponse2002(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[DocumentSearch]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2002 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2002. # noqa: E501 - - - :return: The count of this InlineResponse2002. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2002. - - - :param count: The count of this InlineResponse2002. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2002. # noqa: E501 - - - :return: The next of this InlineResponse2002. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2002. - - - :param next: The next of this InlineResponse2002. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2002. # noqa: E501 - - - :return: The previous of this InlineResponse2002. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2002. - - - :param previous: The previous of this InlineResponse2002. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2002. # noqa: E501 - - - :return: The results of this InlineResponse2002. # noqa: E501 - :rtype: list[DocumentSearch] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2002. - - - :param results: The results of this InlineResponse2002. # noqa: E501 - :type: list[DocumentSearch] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2002): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_3.py b/signrequest_python_client/models/inline_response_200_3.py deleted file mode 100644 index de24862..0000000 --- a/signrequest_python_client/models/inline_response_200_3.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document import Document # noqa: F401,E501 - - -class InlineResponse2003(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[Document]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2003 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2003. # noqa: E501 - - - :return: The count of this InlineResponse2003. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2003. - - - :param count: The count of this InlineResponse2003. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2003. # noqa: E501 - - - :return: The next of this InlineResponse2003. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2003. - - - :param next: The next of this InlineResponse2003. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2003. # noqa: E501 - - - :return: The previous of this InlineResponse2003. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2003. - - - :param previous: The previous of this InlineResponse2003. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2003. # noqa: E501 - - - :return: The results of this InlineResponse2003. # noqa: E501 - :rtype: list[Document] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2003. - - - :param results: The results of this InlineResponse2003. # noqa: E501 - :type: list[Document] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2003): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_4.py b/signrequest_python_client/models/inline_response_200_4.py deleted file mode 100644 index 6c09b68..0000000 --- a/signrequest_python_client/models/inline_response_200_4.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.event import Event # noqa: F401,E501 - - -class InlineResponse2004(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[Event]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2004 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2004. # noqa: E501 - - - :return: The count of this InlineResponse2004. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2004. - - - :param count: The count of this InlineResponse2004. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2004. # noqa: E501 - - - :return: The next of this InlineResponse2004. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2004. - - - :param next: The next of this InlineResponse2004. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2004. # noqa: E501 - - - :return: The previous of this InlineResponse2004. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2004. - - - :param previous: The previous of this InlineResponse2004. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2004. # noqa: E501 - - - :return: The results of this InlineResponse2004. # noqa: E501 - :rtype: list[Event] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2004. - - - :param results: The results of this InlineResponse2004. # noqa: E501 - :type: list[Event] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2004): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_5.py b/signrequest_python_client/models/inline_response_200_5.py deleted file mode 100644 index 80df36f..0000000 --- a/signrequest_python_client/models/inline_response_200_5.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.sign_request import SignRequest # noqa: F401,E501 - - -class InlineResponse2005(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[SignRequest]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2005 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2005. # noqa: E501 - - - :return: The count of this InlineResponse2005. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2005. - - - :param count: The count of this InlineResponse2005. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2005. # noqa: E501 - - - :return: The next of this InlineResponse2005. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2005. - - - :param next: The next of this InlineResponse2005. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2005. # noqa: E501 - - - :return: The previous of this InlineResponse2005. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2005. - - - :param previous: The previous of this InlineResponse2005. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2005. # noqa: E501 - - - :return: The results of this InlineResponse2005. # noqa: E501 - :rtype: list[SignRequest] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2005. - - - :param results: The results of this InlineResponse2005. # noqa: E501 - :type: list[SignRequest] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2005): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_6.py b/signrequest_python_client/models/inline_response_200_6.py deleted file mode 100644 index 036a14c..0000000 --- a/signrequest_python_client/models/inline_response_200_6.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.team_member import TeamMember # noqa: F401,E501 - - -class InlineResponse2006(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[TeamMember]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2006 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2006. # noqa: E501 - - - :return: The count of this InlineResponse2006. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2006. - - - :param count: The count of this InlineResponse2006. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2006. # noqa: E501 - - - :return: The next of this InlineResponse2006. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2006. - - - :param next: The next of this InlineResponse2006. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2006. # noqa: E501 - - - :return: The previous of this InlineResponse2006. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2006. - - - :param previous: The previous of this InlineResponse2006. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2006. # noqa: E501 - - - :return: The results of this InlineResponse2006. # noqa: E501 - :rtype: list[TeamMember] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2006. - - - :param results: The results of this InlineResponse2006. # noqa: E501 - :type: list[TeamMember] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2006): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_7.py b/signrequest_python_client/models/inline_response_200_7.py deleted file mode 100644 index 4f97afe..0000000 --- a/signrequest_python_client/models/inline_response_200_7.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.team import Team # noqa: F401,E501 - - -class InlineResponse2007(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[Team]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2007 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2007. # noqa: E501 - - - :return: The count of this InlineResponse2007. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2007. - - - :param count: The count of this InlineResponse2007. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2007. # noqa: E501 - - - :return: The next of this InlineResponse2007. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2007. - - - :param next: The next of this InlineResponse2007. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2007. # noqa: E501 - - - :return: The previous of this InlineResponse2007. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2007. - - - :param previous: The previous of this InlineResponse2007. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2007. # noqa: E501 - - - :return: The results of this InlineResponse2007. # noqa: E501 - :rtype: list[Team] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2007. - - - :param results: The results of this InlineResponse2007. # noqa: E501 - :type: list[Team] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2007): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_8.py b/signrequest_python_client/models/inline_response_200_8.py deleted file mode 100644 index 72f4967..0000000 --- a/signrequest_python_client/models/inline_response_200_8.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.template import Template # noqa: F401,E501 - - -class InlineResponse2008(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[Template]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2008 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2008. # noqa: E501 - - - :return: The count of this InlineResponse2008. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2008. - - - :param count: The count of this InlineResponse2008. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2008. # noqa: E501 - - - :return: The next of this InlineResponse2008. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2008. - - - :param next: The next of this InlineResponse2008. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2008. # noqa: E501 - - - :return: The previous of this InlineResponse2008. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2008. - - - :param previous: The previous of this InlineResponse2008. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2008. # noqa: E501 - - - :return: The results of this InlineResponse2008. # noqa: E501 - :rtype: list[Template] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2008. - - - :param results: The results of this InlineResponse2008. # noqa: E501 - :type: list[Template] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2008): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_200_9.py b/signrequest_python_client/models/inline_response_200_9.py deleted file mode 100644 index 7087499..0000000 --- a/signrequest_python_client/models/inline_response_200_9.py +++ /dev/null @@ -1,194 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.webhook_subscription import WebhookSubscription # noqa: F401,E501 - - -class InlineResponse2009(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'count': 'int', - 'next': 'str', - 'previous': 'str', - 'results': 'list[WebhookSubscription]' - } - - attribute_map = { - 'count': 'count', - 'next': 'next', - 'previous': 'previous', - 'results': 'results' - } - - def __init__(self, count=None, next=None, previous=None, results=None): # noqa: E501 - """InlineResponse2009 - a model defined in Swagger""" # noqa: E501 - - self._count = None - self._next = None - self._previous = None - self._results = None - self.discriminator = None - - self.count = count - if next is not None: - self.next = next - if previous is not None: - self.previous = previous - self.results = results - - @property - def count(self): - """Gets the count of this InlineResponse2009. # noqa: E501 - - - :return: The count of this InlineResponse2009. # noqa: E501 - :rtype: int - """ - return self._count - - @count.setter - def count(self, count): - """Sets the count of this InlineResponse2009. - - - :param count: The count of this InlineResponse2009. # noqa: E501 - :type: int - """ - if count is None: - raise ValueError("Invalid value for `count`, must not be `None`") # noqa: E501 - - self._count = count - - @property - def next(self): - """Gets the next of this InlineResponse2009. # noqa: E501 - - - :return: The next of this InlineResponse2009. # noqa: E501 - :rtype: str - """ - return self._next - - @next.setter - def next(self, next): - """Sets the next of this InlineResponse2009. - - - :param next: The next of this InlineResponse2009. # noqa: E501 - :type: str - """ - - self._next = next - - @property - def previous(self): - """Gets the previous of this InlineResponse2009. # noqa: E501 - - - :return: The previous of this InlineResponse2009. # noqa: E501 - :rtype: str - """ - return self._previous - - @previous.setter - def previous(self, previous): - """Sets the previous of this InlineResponse2009. - - - :param previous: The previous of this InlineResponse2009. # noqa: E501 - :type: str - """ - - self._previous = previous - - @property - def results(self): - """Gets the results of this InlineResponse2009. # noqa: E501 - - - :return: The results of this InlineResponse2009. # noqa: E501 - :rtype: list[WebhookSubscription] - """ - return self._results - - @results.setter - def results(self, results): - """Sets the results of this InlineResponse2009. - - - :param results: The results of this InlineResponse2009. # noqa: E501 - :type: list[WebhookSubscription] - """ - if results is None: - raise ValueError("Invalid value for `results`, must not be `None`") # noqa: E501 - - self._results = results - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2009): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_201.py b/signrequest_python_client/models/inline_response_201.py deleted file mode 100644 index 9864d76..0000000 --- a/signrequest_python_client/models/inline_response_201.py +++ /dev/null @@ -1,146 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlineResponse201(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'cancelled': 'bool', - 'detail': 'str' - } - - attribute_map = { - 'cancelled': 'cancelled', - 'detail': 'detail' - } - - def __init__(self, cancelled=None, detail=None): # noqa: E501 - """InlineResponse201 - a model defined in Swagger""" # noqa: E501 - - self._cancelled = None - self._detail = None - self.discriminator = None - - self.cancelled = cancelled - self.detail = detail - - @property - def cancelled(self): - """Gets the cancelled of this InlineResponse201. # noqa: E501 - - - :return: The cancelled of this InlineResponse201. # noqa: E501 - :rtype: bool - """ - return self._cancelled - - @cancelled.setter - def cancelled(self, cancelled): - """Sets the cancelled of this InlineResponse201. - - - :param cancelled: The cancelled of this InlineResponse201. # noqa: E501 - :type: bool - """ - if cancelled is None: - raise ValueError("Invalid value for `cancelled`, must not be `None`") # noqa: E501 - - self._cancelled = cancelled - - @property - def detail(self): - """Gets the detail of this InlineResponse201. # noqa: E501 - - - :return: The detail of this InlineResponse201. # noqa: E501 - :rtype: str - """ - return self._detail - - @detail.setter - def detail(self, detail): - """Sets the detail of this InlineResponse201. - - - :param detail: The detail of this InlineResponse201. # noqa: E501 - :type: str - """ - if detail is None: - raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 - allowed_values = ["OK"] # noqa: E501 - if detail not in allowed_values: - raise ValueError( - "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 - .format(detail, allowed_values) - ) - - self._detail = detail - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse201): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_response_201_1.py b/signrequest_python_client/models/inline_response_201_1.py deleted file mode 100644 index 3ee35ef..0000000 --- a/signrequest_python_client/models/inline_response_201_1.py +++ /dev/null @@ -1,119 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlineResponse2011(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'detail': 'str' - } - - attribute_map = { - 'detail': 'detail' - } - - def __init__(self, detail=None): # noqa: E501 - """InlineResponse2011 - a model defined in Swagger""" # noqa: E501 - - self._detail = None - self.discriminator = None - - self.detail = detail - - @property - def detail(self): - """Gets the detail of this InlineResponse2011. # noqa: E501 - - - :return: The detail of this InlineResponse2011. # noqa: E501 - :rtype: str - """ - return self._detail - - @detail.setter - def detail(self, detail): - """Sets the detail of this InlineResponse2011. - - - :param detail: The detail of this InlineResponse2011. # noqa: E501 - :type: str - """ - if detail is None: - raise ValueError("Invalid value for `detail`, must not be `None`") # noqa: E501 - allowed_values = ["OK"] # noqa: E501 - if detail not in allowed_values: - raise ValueError( - "Invalid value for `detail` ({0}), must be one of {1}" # noqa: E501 - .format(detail, allowed_values) - ) - - self._detail = detail - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineResponse2011): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_sign_request.py b/signrequest_python_client/models/inline_sign_request.py deleted file mode 100644 index 396efa1..0000000 --- a/signrequest_python_client/models/inline_sign_request.py +++ /dev/null @@ -1,605 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 -from signrequest_python_client.models.signer import Signer # noqa: F401,E501 - - -class InlineSignRequest(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'from_email': 'str', - 'from_email_name': 'str', - 'is_being_prepared': 'bool', - 'prepare_url': 'str', - 'redirect_url': 'str', - 'required_attachments': 'list[RequiredAttachment]', - 'disable_attachments': 'bool', - 'disable_text_signatures': 'bool', - 'disable_text': 'bool', - 'disable_date': 'bool', - 'disable_emails': 'bool', - 'disable_upload_signatures': 'bool', - 'subject': 'str', - 'message': 'str', - 'who': 'str', - 'send_reminders': 'bool', - 'signers': 'list[Signer]', - 'uuid': 'str' - } - - attribute_map = { - 'from_email': 'from_email', - 'from_email_name': 'from_email_name', - 'is_being_prepared': 'is_being_prepared', - 'prepare_url': 'prepare_url', - 'redirect_url': 'redirect_url', - 'required_attachments': 'required_attachments', - 'disable_attachments': 'disable_attachments', - 'disable_text_signatures': 'disable_text_signatures', - 'disable_text': 'disable_text', - 'disable_date': 'disable_date', - 'disable_emails': 'disable_emails', - 'disable_upload_signatures': 'disable_upload_signatures', - 'subject': 'subject', - 'message': 'message', - 'who': 'who', - 'send_reminders': 'send_reminders', - 'signers': 'signers', - 'uuid': 'uuid' - } - - def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who=None, send_reminders=None, signers=None, uuid=None): # noqa: E501 - """InlineSignRequest - a model defined in Swagger""" # noqa: E501 - - self._from_email = None - self._from_email_name = None - self._is_being_prepared = None - self._prepare_url = None - self._redirect_url = None - self._required_attachments = None - self._disable_attachments = None - self._disable_text_signatures = None - self._disable_text = None - self._disable_date = None - self._disable_emails = None - self._disable_upload_signatures = None - self._subject = None - self._message = None - self._who = None - self._send_reminders = None - self._signers = None - self._uuid = None - self.discriminator = None - - if from_email is not None: - self.from_email = from_email - if from_email_name is not None: - self.from_email_name = from_email_name - if is_being_prepared is not None: - self.is_being_prepared = is_being_prepared - if prepare_url is not None: - self.prepare_url = prepare_url - if redirect_url is not None: - self.redirect_url = redirect_url - if required_attachments is not None: - self.required_attachments = required_attachments - if disable_attachments is not None: - self.disable_attachments = disable_attachments - if disable_text_signatures is not None: - self.disable_text_signatures = disable_text_signatures - if disable_text is not None: - self.disable_text = disable_text - if disable_date is not None: - self.disable_date = disable_date - if disable_emails is not None: - self.disable_emails = disable_emails - if disable_upload_signatures is not None: - self.disable_upload_signatures = disable_upload_signatures - if subject is not None: - self.subject = subject - if message is not None: - self.message = message - if who is not None: - self.who = who - if send_reminders is not None: - self.send_reminders = send_reminders - if signers is not None: - self.signers = signers - if uuid is not None: - self.uuid = uuid - - @property - def from_email(self): - """Gets the from_email of this InlineSignRequest. # noqa: E501 - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :return: The from_email of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._from_email - - @from_email.setter - def from_email(self, from_email): - """Sets the from_email of this InlineSignRequest. - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :param from_email: The from_email of this InlineSignRequest. # noqa: E501 - :type: str - """ - if from_email is not None and len(from_email) < 1: - raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 - - self._from_email = from_email - - @property - def from_email_name(self): - """Gets the from_email_name of this InlineSignRequest. # noqa: E501 - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :return: The from_email_name of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._from_email_name - - @from_email_name.setter - def from_email_name(self, from_email_name): - """Sets the from_email_name of this InlineSignRequest. - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :param from_email_name: The from_email_name of this InlineSignRequest. # noqa: E501 - :type: str - """ - if from_email_name is not None and len(from_email_name) < 1: - raise ValueError("Invalid value for `from_email_name`, length must be greater than or equal to `1`") # noqa: E501 - - self._from_email_name = from_email_name - - @property - def is_being_prepared(self): - """Gets the is_being_prepared of this InlineSignRequest. # noqa: E501 - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :return: The is_being_prepared of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._is_being_prepared - - @is_being_prepared.setter - def is_being_prepared(self, is_being_prepared): - """Sets the is_being_prepared of this InlineSignRequest. - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :param is_being_prepared: The is_being_prepared of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._is_being_prepared = is_being_prepared - - @property - def prepare_url(self): - """Gets the prepare_url of this InlineSignRequest. # noqa: E501 - - - :return: The prepare_url of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._prepare_url - - @prepare_url.setter - def prepare_url(self, prepare_url): - """Sets the prepare_url of this InlineSignRequest. - - - :param prepare_url: The prepare_url of this InlineSignRequest. # noqa: E501 - :type: str - """ - if prepare_url is not None and len(prepare_url) < 1: - raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._prepare_url = prepare_url - - @property - def redirect_url(self): - """Gets the redirect_url of this InlineSignRequest. # noqa: E501 - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :return: The redirect_url of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._redirect_url - - @redirect_url.setter - def redirect_url(self, redirect_url): - """Sets the redirect_url of this InlineSignRequest. - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :param redirect_url: The redirect_url of this InlineSignRequest. # noqa: E501 - :type: str - """ - if redirect_url is not None and len(redirect_url) < 1: - raise ValueError("Invalid value for `redirect_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._redirect_url = redirect_url - - @property - def required_attachments(self): - """Gets the required_attachments of this InlineSignRequest. # noqa: E501 - - - :return: The required_attachments of this InlineSignRequest. # noqa: E501 - :rtype: list[RequiredAttachment] - """ - return self._required_attachments - - @required_attachments.setter - def required_attachments(self, required_attachments): - """Sets the required_attachments of this InlineSignRequest. - - - :param required_attachments: The required_attachments of this InlineSignRequest. # noqa: E501 - :type: list[RequiredAttachment] - """ - - self._required_attachments = required_attachments - - @property - def disable_attachments(self): - """Gets the disable_attachments of this InlineSignRequest. # noqa: E501 - - Disable uploading/adding of attachments # noqa: E501 - - :return: The disable_attachments of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_attachments - - @disable_attachments.setter - def disable_attachments(self, disable_attachments): - """Sets the disable_attachments of this InlineSignRequest. - - Disable uploading/adding of attachments # noqa: E501 - - :param disable_attachments: The disable_attachments of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_attachments = disable_attachments - - @property - def disable_text_signatures(self): - """Gets the disable_text_signatures of this InlineSignRequest. # noqa: E501 - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :return: The disable_text_signatures of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_text_signatures - - @disable_text_signatures.setter - def disable_text_signatures(self, disable_text_signatures): - """Sets the disable_text_signatures of this InlineSignRequest. - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :param disable_text_signatures: The disable_text_signatures of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_text_signatures = disable_text_signatures - - @property - def disable_text(self): - """Gets the disable_text of this InlineSignRequest. # noqa: E501 - - Disable adding of text # noqa: E501 - - :return: The disable_text of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_text - - @disable_text.setter - def disable_text(self, disable_text): - """Sets the disable_text of this InlineSignRequest. - - Disable adding of text # noqa: E501 - - :param disable_text: The disable_text of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_text = disable_text - - @property - def disable_date(self): - """Gets the disable_date of this InlineSignRequest. # noqa: E501 - - Disable adding of dates # noqa: E501 - - :return: The disable_date of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_date - - @disable_date.setter - def disable_date(self, disable_date): - """Sets the disable_date of this InlineSignRequest. - - Disable adding of dates # noqa: E501 - - :param disable_date: The disable_date of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_date = disable_date - - @property - def disable_emails(self): - """Gets the disable_emails of this InlineSignRequest. # noqa: E501 - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :return: The disable_emails of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_emails - - @disable_emails.setter - def disable_emails(self, disable_emails): - """Sets the disable_emails of this InlineSignRequest. - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :param disable_emails: The disable_emails of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_emails = disable_emails - - @property - def disable_upload_signatures(self): - """Gets the disable_upload_signatures of this InlineSignRequest. # noqa: E501 - - Disable usage of uploaded signatures (images) # noqa: E501 - - :return: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_upload_signatures - - @disable_upload_signatures.setter - def disable_upload_signatures(self, disable_upload_signatures): - """Sets the disable_upload_signatures of this InlineSignRequest. - - Disable usage of uploaded signatures (images) # noqa: E501 - - :param disable_upload_signatures: The disable_upload_signatures of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._disable_upload_signatures = disable_upload_signatures - - @property - def subject(self): - """Gets the subject of this InlineSignRequest. # noqa: E501 - - Subject of SignRequest email # noqa: E501 - - :return: The subject of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._subject - - @subject.setter - def subject(self, subject): - """Sets the subject of this InlineSignRequest. - - Subject of SignRequest email # noqa: E501 - - :param subject: The subject of this InlineSignRequest. # noqa: E501 - :type: str - """ - if subject is not None and len(subject) < 1: - raise ValueError("Invalid value for `subject`, length must be greater than or equal to `1`") # noqa: E501 - - self._subject = subject - - @property - def message(self): - """Gets the message of this InlineSignRequest. # noqa: E501 - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :return: The message of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._message - - @message.setter - def message(self, message): - """Sets the message of this InlineSignRequest. - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :param message: The message of this InlineSignRequest. # noqa: E501 - :type: str - """ - if message is not None and len(message) < 1: - raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 - - self._message = message - - @property - def who(self): - """Gets the who of this InlineSignRequest. # noqa: E501 - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :return: The who of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._who - - @who.setter - def who(self, who): - """Sets the who of this InlineSignRequest. - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :param who: The who of this InlineSignRequest. # noqa: E501 - :type: str - """ - allowed_values = ["m", "mo", "o"] # noqa: E501 - if who not in allowed_values: - raise ValueError( - "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 - .format(who, allowed_values) - ) - - self._who = who - - @property - def send_reminders(self): - """Gets the send_reminders of this InlineSignRequest. # noqa: E501 - - Automatically remind signers to sign a document # noqa: E501 - - :return: The send_reminders of this InlineSignRequest. # noqa: E501 - :rtype: bool - """ - return self._send_reminders - - @send_reminders.setter - def send_reminders(self, send_reminders): - """Sets the send_reminders of this InlineSignRequest. - - Automatically remind signers to sign a document # noqa: E501 - - :param send_reminders: The send_reminders of this InlineSignRequest. # noqa: E501 - :type: bool - """ - - self._send_reminders = send_reminders - - @property - def signers(self): - """Gets the signers of this InlineSignRequest. # noqa: E501 - - - :return: The signers of this InlineSignRequest. # noqa: E501 - :rtype: list[Signer] - """ - return self._signers - - @signers.setter - def signers(self, signers): - """Sets the signers of this InlineSignRequest. - - - :param signers: The signers of this InlineSignRequest. # noqa: E501 - :type: list[Signer] - """ - - self._signers = signers - - @property - def uuid(self): - """Gets the uuid of this InlineSignRequest. # noqa: E501 - - - :return: The uuid of this InlineSignRequest. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this InlineSignRequest. - - - :param uuid: The uuid of this InlineSignRequest. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineSignRequest): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_team.py b/signrequest_python_client/models/inline_team.py deleted file mode 100644 index dacb2bd..0000000 --- a/signrequest_python_client/models/inline_team.py +++ /dev/null @@ -1,170 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InlineTeam(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'name': 'str', - 'subdomain': 'str', - 'url': 'str' - } - - attribute_map = { - 'name': 'name', - 'subdomain': 'subdomain', - 'url': 'url' - } - - def __init__(self, name=None, subdomain=None, url=None): # noqa: E501 - """InlineTeam - a model defined in Swagger""" # noqa: E501 - - self._name = None - self._subdomain = None - self._url = None - self.discriminator = None - - if name is not None: - self.name = name - if subdomain is not None: - self.subdomain = subdomain - if url is not None: - self.url = url - - @property - def name(self): - """Gets the name of this InlineTeam. # noqa: E501 - - - :return: The name of this InlineTeam. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this InlineTeam. - - - :param name: The name of this InlineTeam. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def subdomain(self): - """Gets the subdomain of this InlineTeam. # noqa: E501 - - - :return: The subdomain of this InlineTeam. # noqa: E501 - :rtype: str - """ - return self._subdomain - - @subdomain.setter - def subdomain(self, subdomain): - """Sets the subdomain of this InlineTeam. - - - :param subdomain: The subdomain of this InlineTeam. # noqa: E501 - :type: str - """ - if subdomain is not None and len(subdomain) < 1: - raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 - if subdomain is not None and not re.search('^[-a-zA-Z0-9_]+$', subdomain): # noqa: E501 - raise ValueError("Invalid value for `subdomain`, must be a follow pattern or equal to `/^[-a-zA-Z0-9_]+$/`") # noqa: E501 - - self._subdomain = subdomain - - @property - def url(self): - """Gets the url of this InlineTeam. # noqa: E501 - - - :return: The url of this InlineTeam. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this InlineTeam. - - - :param url: The url of this InlineTeam. # noqa: E501 - :type: str - """ - - self._url = url - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineTeam): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/inline_team_member.py b/signrequest_python_client/models/inline_team_member.py deleted file mode 100644 index 876d465..0000000 --- a/signrequest_python_client/models/inline_team_member.py +++ /dev/null @@ -1,246 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.user import User # noqa: F401,E501 - - -class InlineTeamMember(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'uuid': 'str', - 'url': 'str', - 'user': 'User', - 'is_admin': 'bool', - 'is_active': 'bool', - 'is_owner': 'bool' - } - - attribute_map = { - 'uuid': 'uuid', - 'url': 'url', - 'user': 'user', - 'is_admin': 'is_admin', - 'is_active': 'is_active', - 'is_owner': 'is_owner' - } - - def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 - """InlineTeamMember - a model defined in Swagger""" # noqa: E501 - - self._uuid = None - self._url = None - self._user = None - self._is_admin = None - self._is_active = None - self._is_owner = None - self.discriminator = None - - if uuid is not None: - self.uuid = uuid - if url is not None: - self.url = url - if user is not None: - self.user = user - if is_admin is not None: - self.is_admin = is_admin - if is_active is not None: - self.is_active = is_active - if is_owner is not None: - self.is_owner = is_owner - - @property - def uuid(self): - """Gets the uuid of this InlineTeamMember. # noqa: E501 - - - :return: The uuid of this InlineTeamMember. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this InlineTeamMember. - - - :param uuid: The uuid of this InlineTeamMember. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def url(self): - """Gets the url of this InlineTeamMember. # noqa: E501 - - - :return: The url of this InlineTeamMember. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this InlineTeamMember. - - - :param url: The url of this InlineTeamMember. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def user(self): - """Gets the user of this InlineTeamMember. # noqa: E501 - - - :return: The user of this InlineTeamMember. # noqa: E501 - :rtype: User - """ - return self._user - - @user.setter - def user(self, user): - """Sets the user of this InlineTeamMember. - - - :param user: The user of this InlineTeamMember. # noqa: E501 - :type: User - """ - - self._user = user - - @property - def is_admin(self): - """Gets the is_admin of this InlineTeamMember. # noqa: E501 - - - :return: The is_admin of this InlineTeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_admin - - @is_admin.setter - def is_admin(self, is_admin): - """Sets the is_admin of this InlineTeamMember. - - - :param is_admin: The is_admin of this InlineTeamMember. # noqa: E501 - :type: bool - """ - - self._is_admin = is_admin - - @property - def is_active(self): - """Gets the is_active of this InlineTeamMember. # noqa: E501 - - - :return: The is_active of this InlineTeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_active - - @is_active.setter - def is_active(self, is_active): - """Sets the is_active of this InlineTeamMember. - - - :param is_active: The is_active of this InlineTeamMember. # noqa: E501 - :type: bool - """ - - self._is_active = is_active - - @property - def is_owner(self): - """Gets the is_owner of this InlineTeamMember. # noqa: E501 - - - :return: The is_owner of this InlineTeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_owner - - @is_owner.setter - def is_owner(self, is_owner): - """Sets the is_owner of this InlineTeamMember. - - - :param is_owner: The is_owner of this InlineTeamMember. # noqa: E501 - :type: bool - """ - - self._is_owner = is_owner - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InlineTeamMember): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/invite_member.py b/signrequest_python_client/models/invite_member.py deleted file mode 100644 index 62e15f6..0000000 --- a/signrequest_python_client/models/invite_member.py +++ /dev/null @@ -1,167 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class InviteMember(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'email': 'str', - 'is_admin': 'bool', - 'is_owner': 'bool' - } - - attribute_map = { - 'email': 'email', - 'is_admin': 'is_admin', - 'is_owner': 'is_owner' - } - - def __init__(self, email=None, is_admin=False, is_owner=False): # noqa: E501 - """InviteMember - a model defined in Swagger""" # noqa: E501 - - self._email = None - self._is_admin = None - self._is_owner = None - self.discriminator = None - - self.email = email - if is_admin is not None: - self.is_admin = is_admin - if is_owner is not None: - self.is_owner = is_owner - - @property - def email(self): - """Gets the email of this InviteMember. # noqa: E501 - - - :return: The email of this InviteMember. # noqa: E501 - :rtype: str - """ - return self._email - - @email.setter - def email(self, email): - """Sets the email of this InviteMember. - - - :param email: The email of this InviteMember. # noqa: E501 - :type: str - """ - if email is None: - raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 - if email is not None and len(email) < 1: - raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 - - self._email = email - - @property - def is_admin(self): - """Gets the is_admin of this InviteMember. # noqa: E501 - - - :return: The is_admin of this InviteMember. # noqa: E501 - :rtype: bool - """ - return self._is_admin - - @is_admin.setter - def is_admin(self, is_admin): - """Sets the is_admin of this InviteMember. - - - :param is_admin: The is_admin of this InviteMember. # noqa: E501 - :type: bool - """ - - self._is_admin = is_admin - - @property - def is_owner(self): - """Gets the is_owner of this InviteMember. # noqa: E501 - - - :return: The is_owner of this InviteMember. # noqa: E501 - :rtype: bool - """ - return self._is_owner - - @is_owner.setter - def is_owner(self, is_owner): - """Sets the is_owner of this InviteMember. - - - :param is_owner: The is_owner of this InviteMember. # noqa: E501 - :type: bool - """ - - self._is_owner = is_owner - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, InviteMember): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/placeholder.py b/signrequest_python_client/models/placeholder.py deleted file mode 100644 index 05ee1a4..0000000 --- a/signrequest_python_client/models/placeholder.py +++ /dev/null @@ -1,306 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class Placeholder(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'uuid': 'str', - 'type': 'str', - 'page_index': 'int', - 'prefill': 'bool', - 'text': 'str', - 'checkbox_value': 'bool', - 'date_value': 'date', - 'external_id': 'str' - } - - attribute_map = { - 'uuid': 'uuid', - 'type': 'type', - 'page_index': 'page_index', - 'prefill': 'prefill', - 'text': 'text', - 'checkbox_value': 'checkbox_value', - 'date_value': 'date_value', - 'external_id': 'external_id' - } - - def __init__(self, uuid=None, type=None, page_index=None, prefill=None, text=None, checkbox_value=None, date_value=None, external_id=None): # noqa: E501 - """Placeholder - a model defined in Swagger""" # noqa: E501 - - self._uuid = None - self._type = None - self._page_index = None - self._prefill = None - self._text = None - self._checkbox_value = None - self._date_value = None - self._external_id = None - self.discriminator = None - - if uuid is not None: - self.uuid = uuid - if type is not None: - self.type = type - self.page_index = page_index - self.prefill = prefill - if text is not None: - self.text = text - if checkbox_value is not None: - self.checkbox_value = checkbox_value - if date_value is not None: - self.date_value = date_value - if external_id is not None: - self.external_id = external_id - - @property - def uuid(self): - """Gets the uuid of this Placeholder. # noqa: E501 - - - :return: The uuid of this Placeholder. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this Placeholder. - - - :param uuid: The uuid of this Placeholder. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def type(self): - """Gets the type of this Placeholder. # noqa: E501 - - - :return: The type of this Placeholder. # noqa: E501 - :rtype: str - """ - return self._type - - @type.setter - def type(self, type): - """Sets the type of this Placeholder. - - - :param type: The type of this Placeholder. # noqa: E501 - :type: str - """ - allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 - if type not in allowed_values: - raise ValueError( - "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 - .format(type, allowed_values) - ) - - self._type = type - - @property - def page_index(self): - """Gets the page_index of this Placeholder. # noqa: E501 - - - :return: The page_index of this Placeholder. # noqa: E501 - :rtype: int - """ - return self._page_index - - @page_index.setter - def page_index(self, page_index): - """Sets the page_index of this Placeholder. - - - :param page_index: The page_index of this Placeholder. # noqa: E501 - :type: int - """ - if page_index is None: - raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 - - self._page_index = page_index - - @property - def prefill(self): - """Gets the prefill of this Placeholder. # noqa: E501 - - - :return: The prefill of this Placeholder. # noqa: E501 - :rtype: bool - """ - return self._prefill - - @prefill.setter - def prefill(self, prefill): - """Sets the prefill of this Placeholder. - - - :param prefill: The prefill of this Placeholder. # noqa: E501 - :type: bool - """ - if prefill is None: - raise ValueError("Invalid value for `prefill`, must not be `None`") # noqa: E501 - - self._prefill = prefill - - @property - def text(self): - """Gets the text of this Placeholder. # noqa: E501 - - - :return: The text of this Placeholder. # noqa: E501 - :rtype: str - """ - return self._text - - @text.setter - def text(self, text): - """Sets the text of this Placeholder. - - - :param text: The text of this Placeholder. # noqa: E501 - :type: str - """ - - self._text = text - - @property - def checkbox_value(self): - """Gets the checkbox_value of this Placeholder. # noqa: E501 - - - :return: The checkbox_value of this Placeholder. # noqa: E501 - :rtype: bool - """ - return self._checkbox_value - - @checkbox_value.setter - def checkbox_value(self, checkbox_value): - """Sets the checkbox_value of this Placeholder. - - - :param checkbox_value: The checkbox_value of this Placeholder. # noqa: E501 - :type: bool - """ - - self._checkbox_value = checkbox_value - - @property - def date_value(self): - """Gets the date_value of this Placeholder. # noqa: E501 - - - :return: The date_value of this Placeholder. # noqa: E501 - :rtype: date - """ - return self._date_value - - @date_value.setter - def date_value(self, date_value): - """Sets the date_value of this Placeholder. - - - :param date_value: The date_value of this Placeholder. # noqa: E501 - :type: date - """ - - self._date_value = date_value - - @property - def external_id(self): - """Gets the external_id of this Placeholder. # noqa: E501 - - - :return: The external_id of this Placeholder. # noqa: E501 - :rtype: str - """ - return self._external_id - - @external_id.setter - def external_id(self, external_id): - """Sets the external_id of this Placeholder. - - - :param external_id: The external_id of this Placeholder. # noqa: E501 - :type: str - """ - if external_id is not None and len(external_id) > 255: - raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 - - self._external_id = external_id - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Placeholder): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/required_attachment.py b/signrequest_python_client/models/required_attachment.py deleted file mode 100644 index f44336b..0000000 --- a/signrequest_python_client/models/required_attachment.py +++ /dev/null @@ -1,145 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class RequiredAttachment(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'name': 'str', - 'uuid': 'str' - } - - attribute_map = { - 'name': 'name', - 'uuid': 'uuid' - } - - def __init__(self, name=None, uuid=None): # noqa: E501 - """RequiredAttachment - a model defined in Swagger""" # noqa: E501 - - self._name = None - self._uuid = None - self.discriminator = None - - self.name = name - if uuid is not None: - self.uuid = uuid - - @property - def name(self): - """Gets the name of this RequiredAttachment. # noqa: E501 - - - :return: The name of this RequiredAttachment. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this RequiredAttachment. - - - :param name: The name of this RequiredAttachment. # noqa: E501 - :type: str - """ - if name is None: - raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 - if name is not None and len(name) > 255: - raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def uuid(self): - """Gets the uuid of this RequiredAttachment. # noqa: E501 - - - :return: The uuid of this RequiredAttachment. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this RequiredAttachment. - - - :param uuid: The uuid of this RequiredAttachment. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, RequiredAttachment): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/sign_request.py b/signrequest_python_client/models/sign_request.py deleted file mode 100644 index f069864..0000000 --- a/signrequest_python_client/models/sign_request.py +++ /dev/null @@ -1,719 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 -from signrequest_python_client.models.signer import Signer # noqa: F401,E501 - - -class SignRequest(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'from_email': 'str', - 'from_email_name': 'str', - 'is_being_prepared': 'bool', - 'prepare_url': 'str', - 'redirect_url': 'str', - 'required_attachments': 'list[RequiredAttachment]', - 'disable_attachments': 'bool', - 'disable_text_signatures': 'bool', - 'disable_text': 'bool', - 'disable_date': 'bool', - 'disable_emails': 'bool', - 'disable_upload_signatures': 'bool', - 'subject': 'str', - 'message': 'str', - 'who': 'str', - 'send_reminders': 'bool', - 'signers': 'list[Signer]', - 'uuid': 'str', - 'url': 'str', - 'document': 'str', - 'integration': 'str', - 'integration_data': 'str' - } - - attribute_map = { - 'from_email': 'from_email', - 'from_email_name': 'from_email_name', - 'is_being_prepared': 'is_being_prepared', - 'prepare_url': 'prepare_url', - 'redirect_url': 'redirect_url', - 'required_attachments': 'required_attachments', - 'disable_attachments': 'disable_attachments', - 'disable_text_signatures': 'disable_text_signatures', - 'disable_text': 'disable_text', - 'disable_date': 'disable_date', - 'disable_emails': 'disable_emails', - 'disable_upload_signatures': 'disable_upload_signatures', - 'subject': 'subject', - 'message': 'message', - 'who': 'who', - 'send_reminders': 'send_reminders', - 'signers': 'signers', - 'uuid': 'uuid', - 'url': 'url', - 'document': 'document', - 'integration': 'integration', - 'integration_data': 'integration_data' - } - - def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None): # noqa: E501 - """SignRequest - a model defined in Swagger""" # noqa: E501 - - self._from_email = None - self._from_email_name = None - self._is_being_prepared = None - self._prepare_url = None - self._redirect_url = None - self._required_attachments = None - self._disable_attachments = None - self._disable_text_signatures = None - self._disable_text = None - self._disable_date = None - self._disable_emails = None - self._disable_upload_signatures = None - self._subject = None - self._message = None - self._who = None - self._send_reminders = None - self._signers = None - self._uuid = None - self._url = None - self._document = None - self._integration = None - self._integration_data = None - self.discriminator = None - - if from_email is not None: - self.from_email = from_email - if from_email_name is not None: - self.from_email_name = from_email_name - if is_being_prepared is not None: - self.is_being_prepared = is_being_prepared - if prepare_url is not None: - self.prepare_url = prepare_url - if redirect_url is not None: - self.redirect_url = redirect_url - if required_attachments is not None: - self.required_attachments = required_attachments - if disable_attachments is not None: - self.disable_attachments = disable_attachments - if disable_text_signatures is not None: - self.disable_text_signatures = disable_text_signatures - if disable_text is not None: - self.disable_text = disable_text - if disable_date is not None: - self.disable_date = disable_date - if disable_emails is not None: - self.disable_emails = disable_emails - if disable_upload_signatures is not None: - self.disable_upload_signatures = disable_upload_signatures - if subject is not None: - self.subject = subject - if message is not None: - self.message = message - if who is not None: - self.who = who - if send_reminders is not None: - self.send_reminders = send_reminders - self.signers = signers - if uuid is not None: - self.uuid = uuid - if url is not None: - self.url = url - self.document = document - if integration is not None: - self.integration = integration - if integration_data is not None: - self.integration_data = integration_data - - @property - def from_email(self): - """Gets the from_email of this SignRequest. # noqa: E501 - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :return: The from_email of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._from_email - - @from_email.setter - def from_email(self, from_email): - """Sets the from_email of this SignRequest. - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :param from_email: The from_email of this SignRequest. # noqa: E501 - :type: str - """ - if from_email is not None and len(from_email) > 255: - raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 - if from_email is not None and len(from_email) < 1: - raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 - - self._from_email = from_email - - @property - def from_email_name(self): - """Gets the from_email_name of this SignRequest. # noqa: E501 - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :return: The from_email_name of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._from_email_name - - @from_email_name.setter - def from_email_name(self, from_email_name): - """Sets the from_email_name of this SignRequest. - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :param from_email_name: The from_email_name of this SignRequest. # noqa: E501 - :type: str - """ - if from_email_name is not None and len(from_email_name) > 255: - raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 - - self._from_email_name = from_email_name - - @property - def is_being_prepared(self): - """Gets the is_being_prepared of this SignRequest. # noqa: E501 - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :return: The is_being_prepared of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._is_being_prepared - - @is_being_prepared.setter - def is_being_prepared(self, is_being_prepared): - """Sets the is_being_prepared of this SignRequest. - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :param is_being_prepared: The is_being_prepared of this SignRequest. # noqa: E501 - :type: bool - """ - - self._is_being_prepared = is_being_prepared - - @property - def prepare_url(self): - """Gets the prepare_url of this SignRequest. # noqa: E501 - - - :return: The prepare_url of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._prepare_url - - @prepare_url.setter - def prepare_url(self, prepare_url): - """Sets the prepare_url of this SignRequest. - - - :param prepare_url: The prepare_url of this SignRequest. # noqa: E501 - :type: str - """ - if prepare_url is not None and len(prepare_url) < 1: - raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._prepare_url = prepare_url - - @property - def redirect_url(self): - """Gets the redirect_url of this SignRequest. # noqa: E501 - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :return: The redirect_url of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._redirect_url - - @redirect_url.setter - def redirect_url(self, redirect_url): - """Sets the redirect_url of this SignRequest. - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :param redirect_url: The redirect_url of this SignRequest. # noqa: E501 - :type: str - """ - if redirect_url is not None and len(redirect_url) > 2100: - raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._redirect_url = redirect_url - - @property - def required_attachments(self): - """Gets the required_attachments of this SignRequest. # noqa: E501 - - Attachments that signers are required to upload # noqa: E501 - - :return: The required_attachments of this SignRequest. # noqa: E501 - :rtype: list[RequiredAttachment] - """ - return self._required_attachments - - @required_attachments.setter - def required_attachments(self, required_attachments): - """Sets the required_attachments of this SignRequest. - - Attachments that signers are required to upload # noqa: E501 - - :param required_attachments: The required_attachments of this SignRequest. # noqa: E501 - :type: list[RequiredAttachment] - """ - - self._required_attachments = required_attachments - - @property - def disable_attachments(self): - """Gets the disable_attachments of this SignRequest. # noqa: E501 - - Disable uploading/adding of attachments # noqa: E501 - - :return: The disable_attachments of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_attachments - - @disable_attachments.setter - def disable_attachments(self, disable_attachments): - """Sets the disable_attachments of this SignRequest. - - Disable uploading/adding of attachments # noqa: E501 - - :param disable_attachments: The disable_attachments of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_attachments = disable_attachments - - @property - def disable_text_signatures(self): - """Gets the disable_text_signatures of this SignRequest. # noqa: E501 - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :return: The disable_text_signatures of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_text_signatures - - @disable_text_signatures.setter - def disable_text_signatures(self, disable_text_signatures): - """Sets the disable_text_signatures of this SignRequest. - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :param disable_text_signatures: The disable_text_signatures of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_text_signatures = disable_text_signatures - - @property - def disable_text(self): - """Gets the disable_text of this SignRequest. # noqa: E501 - - Disable adding of text # noqa: E501 - - :return: The disable_text of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_text - - @disable_text.setter - def disable_text(self, disable_text): - """Sets the disable_text of this SignRequest. - - Disable adding of text # noqa: E501 - - :param disable_text: The disable_text of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_text = disable_text - - @property - def disable_date(self): - """Gets the disable_date of this SignRequest. # noqa: E501 - - Disable adding of dates # noqa: E501 - - :return: The disable_date of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_date - - @disable_date.setter - def disable_date(self, disable_date): - """Sets the disable_date of this SignRequest. - - Disable adding of dates # noqa: E501 - - :param disable_date: The disable_date of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_date = disable_date - - @property - def disable_emails(self): - """Gets the disable_emails of this SignRequest. # noqa: E501 - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :return: The disable_emails of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_emails - - @disable_emails.setter - def disable_emails(self, disable_emails): - """Sets the disable_emails of this SignRequest. - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :param disable_emails: The disable_emails of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_emails = disable_emails - - @property - def disable_upload_signatures(self): - """Gets the disable_upload_signatures of this SignRequest. # noqa: E501 - - Disable usage of uploaded signatures (images) # noqa: E501 - - :return: The disable_upload_signatures of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._disable_upload_signatures - - @disable_upload_signatures.setter - def disable_upload_signatures(self, disable_upload_signatures): - """Sets the disable_upload_signatures of this SignRequest. - - Disable usage of uploaded signatures (images) # noqa: E501 - - :param disable_upload_signatures: The disable_upload_signatures of this SignRequest. # noqa: E501 - :type: bool - """ - - self._disable_upload_signatures = disable_upload_signatures - - @property - def subject(self): - """Gets the subject of this SignRequest. # noqa: E501 - - Subject of SignRequest email # noqa: E501 - - :return: The subject of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._subject - - @subject.setter - def subject(self, subject): - """Sets the subject of this SignRequest. - - Subject of SignRequest email # noqa: E501 - - :param subject: The subject of this SignRequest. # noqa: E501 - :type: str - """ - if subject is not None and len(subject) > 512: - raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 - - self._subject = subject - - @property - def message(self): - """Gets the message of this SignRequest. # noqa: E501 - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :return: The message of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._message - - @message.setter - def message(self, message): - """Sets the message of this SignRequest. - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :param message: The message of this SignRequest. # noqa: E501 - :type: str - """ - - self._message = message - - @property - def who(self): - """Gets the who of this SignRequest. # noqa: E501 - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :return: The who of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._who - - @who.setter - def who(self, who): - """Sets the who of this SignRequest. - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :param who: The who of this SignRequest. # noqa: E501 - :type: str - """ - allowed_values = ["m", "mo", "o"] # noqa: E501 - if who not in allowed_values: - raise ValueError( - "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 - .format(who, allowed_values) - ) - - self._who = who - - @property - def send_reminders(self): - """Gets the send_reminders of this SignRequest. # noqa: E501 - - Automatically remind signers to sign a document # noqa: E501 - - :return: The send_reminders of this SignRequest. # noqa: E501 - :rtype: bool - """ - return self._send_reminders - - @send_reminders.setter - def send_reminders(self, send_reminders): - """Sets the send_reminders of this SignRequest. - - Automatically remind signers to sign a document # noqa: E501 - - :param send_reminders: The send_reminders of this SignRequest. # noqa: E501 - :type: bool - """ - - self._send_reminders = send_reminders - - @property - def signers(self): - """Gets the signers of this SignRequest. # noqa: E501 - - - :return: The signers of this SignRequest. # noqa: E501 - :rtype: list[Signer] - """ - return self._signers - - @signers.setter - def signers(self, signers): - """Sets the signers of this SignRequest. - - - :param signers: The signers of this SignRequest. # noqa: E501 - :type: list[Signer] - """ - if signers is None: - raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 - - self._signers = signers - - @property - def uuid(self): - """Gets the uuid of this SignRequest. # noqa: E501 - - - :return: The uuid of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this SignRequest. - - - :param uuid: The uuid of this SignRequest. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def url(self): - """Gets the url of this SignRequest. # noqa: E501 - - - :return: The url of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this SignRequest. - - - :param url: The url of this SignRequest. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def document(self): - """Gets the document of this SignRequest. # noqa: E501 - - - :return: The document of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._document - - @document.setter - def document(self, document): - """Sets the document of this SignRequest. - - - :param document: The document of this SignRequest. # noqa: E501 - :type: str - """ - if document is None: - raise ValueError("Invalid value for `document`, must not be `None`") # noqa: E501 - - self._document = document - - @property - def integration(self): - """Gets the integration of this SignRequest. # noqa: E501 - - - :return: The integration of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._integration - - @integration.setter - def integration(self, integration): - """Sets the integration of this SignRequest. - - - :param integration: The integration of this SignRequest. # noqa: E501 - :type: str - """ - allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 - if integration not in allowed_values: - raise ValueError( - "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 - .format(integration, allowed_values) - ) - - self._integration = integration - - @property - def integration_data(self): - """Gets the integration_data of this SignRequest. # noqa: E501 - - - :return: The integration_data of this SignRequest. # noqa: E501 - :rtype: str - """ - return self._integration_data - - @integration_data.setter - def integration_data(self, integration_data): - """Sets the integration_data of this SignRequest. - - - :param integration_data: The integration_data of this SignRequest. # noqa: E501 - :type: str - """ - - self._integration_data = integration_data - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, SignRequest): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/sign_request_quick_create.py b/signrequest_python_client/models/sign_request_quick_create.py deleted file mode 100644 index 59d98c7..0000000 --- a/signrequest_python_client/models/sign_request_quick_create.py +++ /dev/null @@ -1,1093 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.file_from_sf import FileFromSf # noqa: F401,E501 -from signrequest_python_client.models.inline_integration_data import InlineIntegrationData # noqa: F401,E501 -from signrequest_python_client.models.inline_prefill_tags import InlinePrefillTags # noqa: F401,E501 -from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 -from signrequest_python_client.models.signer import Signer # noqa: F401,E501 - - -class SignRequestQuickCreate(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'from_email': 'str', - 'from_email_name': 'str', - 'is_being_prepared': 'bool', - 'prepare_url': 'str', - 'redirect_url': 'str', - 'required_attachments': 'list[RequiredAttachment]', - 'disable_attachments': 'bool', - 'disable_text_signatures': 'bool', - 'disable_text': 'bool', - 'disable_date': 'bool', - 'disable_emails': 'bool', - 'disable_upload_signatures': 'bool', - 'subject': 'str', - 'message': 'str', - 'who': 'str', - 'send_reminders': 'bool', - 'signers': 'list[Signer]', - 'uuid': 'str', - 'url': 'str', - 'document': 'str', - 'integration': 'str', - 'integration_data': 'str', - 'name': 'str', - 'external_id': 'str', - 'frontend_id': 'str', - 'file': 'str', - 'file_from_url': 'str', - 'events_callback_url': 'str', - 'file_from_content': 'str', - 'file_from_content_name': 'str', - 'template': 'str', - 'prefill_tags': 'list[InlinePrefillTags]', - 'integrations': 'list[InlineIntegrationData]', - 'file_from_sf': 'FileFromSf', - 'auto_delete_days': 'int' - } - - attribute_map = { - 'from_email': 'from_email', - 'from_email_name': 'from_email_name', - 'is_being_prepared': 'is_being_prepared', - 'prepare_url': 'prepare_url', - 'redirect_url': 'redirect_url', - 'required_attachments': 'required_attachments', - 'disable_attachments': 'disable_attachments', - 'disable_text_signatures': 'disable_text_signatures', - 'disable_text': 'disable_text', - 'disable_date': 'disable_date', - 'disable_emails': 'disable_emails', - 'disable_upload_signatures': 'disable_upload_signatures', - 'subject': 'subject', - 'message': 'message', - 'who': 'who', - 'send_reminders': 'send_reminders', - 'signers': 'signers', - 'uuid': 'uuid', - 'url': 'url', - 'document': 'document', - 'integration': 'integration', - 'integration_data': 'integration_data', - 'name': 'name', - 'external_id': 'external_id', - 'frontend_id': 'frontend_id', - 'file': 'file', - 'file_from_url': 'file_from_url', - 'events_callback_url': 'events_callback_url', - 'file_from_content': 'file_from_content', - 'file_from_content_name': 'file_from_content_name', - 'template': 'template', - 'prefill_tags': 'prefill_tags', - 'integrations': 'integrations', - 'file_from_sf': 'file_from_sf', - 'auto_delete_days': 'auto_delete_days' - } - - def __init__(self, from_email=None, from_email_name=None, is_being_prepared=None, prepare_url=None, redirect_url=None, required_attachments=None, disable_attachments=None, disable_text_signatures=None, disable_text=None, disable_date=None, disable_emails=None, disable_upload_signatures=None, subject=None, message=None, who='o', send_reminders=None, signers=None, uuid=None, url=None, document=None, integration=None, integration_data=None, name=None, external_id=None, frontend_id=None, file=None, file_from_url=None, events_callback_url=None, file_from_content=None, file_from_content_name=None, template=None, prefill_tags=None, integrations=None, file_from_sf=None, auto_delete_days=None): # noqa: E501 - """SignRequestQuickCreate - a model defined in Swagger""" # noqa: E501 - - self._from_email = None - self._from_email_name = None - self._is_being_prepared = None - self._prepare_url = None - self._redirect_url = None - self._required_attachments = None - self._disable_attachments = None - self._disable_text_signatures = None - self._disable_text = None - self._disable_date = None - self._disable_emails = None - self._disable_upload_signatures = None - self._subject = None - self._message = None - self._who = None - self._send_reminders = None - self._signers = None - self._uuid = None - self._url = None - self._document = None - self._integration = None - self._integration_data = None - self._name = None - self._external_id = None - self._frontend_id = None - self._file = None - self._file_from_url = None - self._events_callback_url = None - self._file_from_content = None - self._file_from_content_name = None - self._template = None - self._prefill_tags = None - self._integrations = None - self._file_from_sf = None - self._auto_delete_days = None - self.discriminator = None - - if from_email is not None: - self.from_email = from_email - if from_email_name is not None: - self.from_email_name = from_email_name - if is_being_prepared is not None: - self.is_being_prepared = is_being_prepared - if prepare_url is not None: - self.prepare_url = prepare_url - if redirect_url is not None: - self.redirect_url = redirect_url - if required_attachments is not None: - self.required_attachments = required_attachments - if disable_attachments is not None: - self.disable_attachments = disable_attachments - if disable_text_signatures is not None: - self.disable_text_signatures = disable_text_signatures - if disable_text is not None: - self.disable_text = disable_text - if disable_date is not None: - self.disable_date = disable_date - if disable_emails is not None: - self.disable_emails = disable_emails - if disable_upload_signatures is not None: - self.disable_upload_signatures = disable_upload_signatures - if subject is not None: - self.subject = subject - if message is not None: - self.message = message - if who is not None: - self.who = who - if send_reminders is not None: - self.send_reminders = send_reminders - self.signers = signers - if uuid is not None: - self.uuid = uuid - if url is not None: - self.url = url - if document is not None: - self.document = document - if integration is not None: - self.integration = integration - if integration_data is not None: - self.integration_data = integration_data - if name is not None: - self.name = name - if external_id is not None: - self.external_id = external_id - if frontend_id is not None: - self.frontend_id = frontend_id - if file is not None: - self.file = file - if file_from_url is not None: - self.file_from_url = file_from_url - if events_callback_url is not None: - self.events_callback_url = events_callback_url - if file_from_content is not None: - self.file_from_content = file_from_content - if file_from_content_name is not None: - self.file_from_content_name = file_from_content_name - if template is not None: - self.template = template - if prefill_tags is not None: - self.prefill_tags = prefill_tags - if integrations is not None: - self.integrations = integrations - if file_from_sf is not None: - self.file_from_sf = file_from_sf - if auto_delete_days is not None: - self.auto_delete_days = auto_delete_days - - @property - def from_email(self): - """Gets the from_email of this SignRequestQuickCreate. # noqa: E501 - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :return: The from_email of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._from_email - - @from_email.setter - def from_email(self, from_email): - """Sets the from_email of this SignRequestQuickCreate. - - Email of user sending the SignRequest (must be a validated email) # noqa: E501 - - :param from_email: The from_email of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if from_email is not None and len(from_email) > 255: - raise ValueError("Invalid value for `from_email`, length must be less than or equal to `255`") # noqa: E501 - if from_email is not None and len(from_email) < 1: - raise ValueError("Invalid value for `from_email`, length must be greater than or equal to `1`") # noqa: E501 - - self._from_email = from_email - - @property - def from_email_name(self): - """Gets the from_email_name of this SignRequestQuickCreate. # noqa: E501 - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :return: The from_email_name of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._from_email_name - - @from_email_name.setter - def from_email_name(self, from_email_name): - """Sets the from_email_name of this SignRequestQuickCreate. - - Name to be used in the `From` email header, e.g. `{from_email_name} ` # noqa: E501 - - :param from_email_name: The from_email_name of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if from_email_name is not None and len(from_email_name) > 255: - raise ValueError("Invalid value for `from_email_name`, length must be less than or equal to `255`") # noqa: E501 - - self._from_email_name = from_email_name - - @property - def is_being_prepared(self): - """Gets the is_being_prepared of this SignRequestQuickCreate. # noqa: E501 - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :return: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._is_being_prepared - - @is_being_prepared.setter - def is_being_prepared(self, is_being_prepared): - """Sets the is_being_prepared of this SignRequestQuickCreate. - - Have the sender of a SignRequest prepare the document before sending the request out, see: [prepare using the web interface](#section/Preparing-a-document/Prepare-using-the-web-interface) # noqa: E501 - - :param is_being_prepared: The is_being_prepared of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._is_being_prepared = is_being_prepared - - @property - def prepare_url(self): - """Gets the prepare_url of this SignRequestQuickCreate. # noqa: E501 - - - :return: The prepare_url of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._prepare_url - - @prepare_url.setter - def prepare_url(self, prepare_url): - """Sets the prepare_url of this SignRequestQuickCreate. - - - :param prepare_url: The prepare_url of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if prepare_url is not None and len(prepare_url) < 1: - raise ValueError("Invalid value for `prepare_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._prepare_url = prepare_url - - @property - def redirect_url(self): - """Gets the redirect_url of this SignRequestQuickCreate. # noqa: E501 - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :return: The redirect_url of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._redirect_url - - @redirect_url.setter - def redirect_url(self, redirect_url): - """Sets the redirect_url of this SignRequestQuickCreate. - - URL at which SignRequest will redirect to when a document is signed # noqa: E501 - - :param redirect_url: The redirect_url of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if redirect_url is not None and len(redirect_url) > 2100: - raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._redirect_url = redirect_url - - @property - def required_attachments(self): - """Gets the required_attachments of this SignRequestQuickCreate. # noqa: E501 - - Attachments that signers are required to upload # noqa: E501 - - :return: The required_attachments of this SignRequestQuickCreate. # noqa: E501 - :rtype: list[RequiredAttachment] - """ - return self._required_attachments - - @required_attachments.setter - def required_attachments(self, required_attachments): - """Sets the required_attachments of this SignRequestQuickCreate. - - Attachments that signers are required to upload # noqa: E501 - - :param required_attachments: The required_attachments of this SignRequestQuickCreate. # noqa: E501 - :type: list[RequiredAttachment] - """ - - self._required_attachments = required_attachments - - @property - def disable_attachments(self): - """Gets the disable_attachments of this SignRequestQuickCreate. # noqa: E501 - - Disable uploading/adding of attachments # noqa: E501 - - :return: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_attachments - - @disable_attachments.setter - def disable_attachments(self, disable_attachments): - """Sets the disable_attachments of this SignRequestQuickCreate. - - Disable uploading/adding of attachments # noqa: E501 - - :param disable_attachments: The disable_attachments of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_attachments = disable_attachments - - @property - def disable_text_signatures(self): - """Gets the disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :return: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_text_signatures - - @disable_text_signatures.setter - def disable_text_signatures(self, disable_text_signatures): - """Sets the disable_text_signatures of this SignRequestQuickCreate. - - Disable usage of signatures generated by typing (text) # noqa: E501 - - :param disable_text_signatures: The disable_text_signatures of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_text_signatures = disable_text_signatures - - @property - def disable_text(self): - """Gets the disable_text of this SignRequestQuickCreate. # noqa: E501 - - Disable adding of text # noqa: E501 - - :return: The disable_text of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_text - - @disable_text.setter - def disable_text(self, disable_text): - """Sets the disable_text of this SignRequestQuickCreate. - - Disable adding of text # noqa: E501 - - :param disable_text: The disable_text of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_text = disable_text - - @property - def disable_date(self): - """Gets the disable_date of this SignRequestQuickCreate. # noqa: E501 - - Disable adding of dates # noqa: E501 - - :return: The disable_date of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_date - - @disable_date.setter - def disable_date(self, disable_date): - """Sets the disable_date of this SignRequestQuickCreate. - - Disable adding of dates # noqa: E501 - - :param disable_date: The disable_date of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_date = disable_date - - @property - def disable_emails(self): - """Gets the disable_emails of this SignRequestQuickCreate. # noqa: E501 - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :return: The disable_emails of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_emails - - @disable_emails.setter - def disable_emails(self, disable_emails): - """Sets the disable_emails of this SignRequestQuickCreate. - - Disable all SignRequest status emails as well as the email that contains the signed documents # noqa: E501 - - :param disable_emails: The disable_emails of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_emails = disable_emails - - @property - def disable_upload_signatures(self): - """Gets the disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 - - Disable usage of uploaded signatures (images) # noqa: E501 - - :return: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._disable_upload_signatures - - @disable_upload_signatures.setter - def disable_upload_signatures(self, disable_upload_signatures): - """Sets the disable_upload_signatures of this SignRequestQuickCreate. - - Disable usage of uploaded signatures (images) # noqa: E501 - - :param disable_upload_signatures: The disable_upload_signatures of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._disable_upload_signatures = disable_upload_signatures - - @property - def subject(self): - """Gets the subject of this SignRequestQuickCreate. # noqa: E501 - - Subject of SignRequest email # noqa: E501 - - :return: The subject of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._subject - - @subject.setter - def subject(self, subject): - """Sets the subject of this SignRequestQuickCreate. - - Subject of SignRequest email # noqa: E501 - - :param subject: The subject of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if subject is not None and len(subject) > 512: - raise ValueError("Invalid value for `subject`, length must be less than or equal to `512`") # noqa: E501 - - self._subject = subject - - @property - def message(self): - """Gets the message of this SignRequestQuickCreate. # noqa: E501 - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :return: The message of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._message - - @message.setter - def message(self, message): - """Sets the message of this SignRequestQuickCreate. - - Message to include in SignRequest email, may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong` # noqa: E501 - - :param message: The message of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._message = message - - @property - def who(self): - """Gets the who of this SignRequestQuickCreate. # noqa: E501 - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :return: The who of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._who - - @who.setter - def who(self, who): - """Sets the who of this SignRequestQuickCreate. - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :param who: The who of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - allowed_values = ["m", "mo", "o"] # noqa: E501 - if who not in allowed_values: - raise ValueError( - "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 - .format(who, allowed_values) - ) - - self._who = who - - @property - def send_reminders(self): - """Gets the send_reminders of this SignRequestQuickCreate. # noqa: E501 - - Automatically remind signers to sign a document # noqa: E501 - - :return: The send_reminders of this SignRequestQuickCreate. # noqa: E501 - :rtype: bool - """ - return self._send_reminders - - @send_reminders.setter - def send_reminders(self, send_reminders): - """Sets the send_reminders of this SignRequestQuickCreate. - - Automatically remind signers to sign a document # noqa: E501 - - :param send_reminders: The send_reminders of this SignRequestQuickCreate. # noqa: E501 - :type: bool - """ - - self._send_reminders = send_reminders - - @property - def signers(self): - """Gets the signers of this SignRequestQuickCreate. # noqa: E501 - - - :return: The signers of this SignRequestQuickCreate. # noqa: E501 - :rtype: list[Signer] - """ - return self._signers - - @signers.setter - def signers(self, signers): - """Sets the signers of this SignRequestQuickCreate. - - - :param signers: The signers of this SignRequestQuickCreate. # noqa: E501 - :type: list[Signer] - """ - if signers is None: - raise ValueError("Invalid value for `signers`, must not be `None`") # noqa: E501 - - self._signers = signers - - @property - def uuid(self): - """Gets the uuid of this SignRequestQuickCreate. # noqa: E501 - - - :return: The uuid of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this SignRequestQuickCreate. - - - :param uuid: The uuid of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def url(self): - """Gets the url of this SignRequestQuickCreate. # noqa: E501 - - - :return: The url of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this SignRequestQuickCreate. - - - :param url: The url of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def document(self): - """Gets the document of this SignRequestQuickCreate. # noqa: E501 - - - :return: The document of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._document - - @document.setter - def document(self, document): - """Sets the document of this SignRequestQuickCreate. - - - :param document: The document of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._document = document - - @property - def integration(self): - """Gets the integration of this SignRequestQuickCreate. # noqa: E501 - - - :return: The integration of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._integration - - @integration.setter - def integration(self, integration): - """Sets the integration of this SignRequestQuickCreate. - - - :param integration: The integration of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 - if integration not in allowed_values: - raise ValueError( - "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 - .format(integration, allowed_values) - ) - - self._integration = integration - - @property - def integration_data(self): - """Gets the integration_data of this SignRequestQuickCreate. # noqa: E501 - - - :return: The integration_data of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._integration_data - - @integration_data.setter - def integration_data(self, integration_data): - """Sets the integration_data of this SignRequestQuickCreate. - - - :param integration_data: The integration_data of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._integration_data = integration_data - - @property - def name(self): - """Gets the name of this SignRequestQuickCreate. # noqa: E501 - - Defaults to filename, including extension # noqa: E501 - - :return: The name of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this SignRequestQuickCreate. - - Defaults to filename, including extension # noqa: E501 - - :param name: The name of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if name is not None and len(name) > 255: - raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 - - self._name = name - - @property - def external_id(self): - """Gets the external_id of this SignRequestQuickCreate. # noqa: E501 - - ID used to reference document in external system # noqa: E501 - - :return: The external_id of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._external_id - - @external_id.setter - def external_id(self, external_id): - """Sets the external_id of this SignRequestQuickCreate. - - ID used to reference document in external system # noqa: E501 - - :param external_id: The external_id of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if external_id is not None and len(external_id) > 255: - raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 - - self._external_id = external_id - - @property - def frontend_id(self): - """Gets the frontend_id of this SignRequestQuickCreate. # noqa: E501 - - Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 - - :return: The frontend_id of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._frontend_id - - @frontend_id.setter - def frontend_id(self, frontend_id): - """Sets the frontend_id of this SignRequestQuickCreate. - - Shared secret used in conjunction with SignRequest-js client to grant user access to a document that's not a member of the document's team # noqa: E501 - - :param frontend_id: The frontend_id of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if frontend_id is not None and len(frontend_id) > 255: - raise ValueError("Invalid value for `frontend_id`, length must be less than or equal to `255`") # noqa: E501 - - self._frontend_id = frontend_id - - @property - def file(self): - """Gets the file of this SignRequestQuickCreate. # noqa: E501 - - Temporary URL to original file, expires in five minutes # noqa: E501 - - :return: The file of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._file - - @file.setter - def file(self, file): - """Sets the file of this SignRequestQuickCreate. - - Temporary URL to original file, expires in five minutes # noqa: E501 - - :param file: The file of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._file = file - - @property - def file_from_url(self): - """Gets the file_from_url of this SignRequestQuickCreate. # noqa: E501 - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :return: The file_from_url of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._file_from_url - - @file_from_url.setter - def file_from_url(self, file_from_url): - """Sets the file_from_url of this SignRequestQuickCreate. - - Publicly accessible URL of document to be downloaded by SignRequest # noqa: E501 - - :param file_from_url: The file_from_url of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if file_from_url is not None and len(file_from_url) > 2100: - raise ValueError("Invalid value for `file_from_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._file_from_url = file_from_url - - @property - def events_callback_url(self): - """Gets the events_callback_url of this SignRequestQuickCreate. # noqa: E501 - - URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 - - :return: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._events_callback_url - - @events_callback_url.setter - def events_callback_url(self, events_callback_url): - """Sets the events_callback_url of this SignRequestQuickCreate. - - URL at which to receive [event callbacks](#section/Events/Events-callback) for this document # noqa: E501 - - :param events_callback_url: The events_callback_url of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - if events_callback_url is not None and len(events_callback_url) > 2100: - raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._events_callback_url = events_callback_url - - @property - def file_from_content(self): - """Gets the file_from_content of this SignRequestQuickCreate. # noqa: E501 - - Base64 encoded document content # noqa: E501 - - :return: The file_from_content of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._file_from_content - - @file_from_content.setter - def file_from_content(self, file_from_content): - """Sets the file_from_content of this SignRequestQuickCreate. - - Base64 encoded document content # noqa: E501 - - :param file_from_content: The file_from_content of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._file_from_content = file_from_content - - @property - def file_from_content_name(self): - """Gets the file_from_content_name of this SignRequestQuickCreate. # noqa: E501 - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :return: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._file_from_content_name - - @file_from_content_name.setter - def file_from_content_name(self, file_from_content_name): - """Sets the file_from_content_name of this SignRequestQuickCreate. - - Filename, including extension. Required when using `file_from_content`. # noqa: E501 - - :param file_from_content_name: The file_from_content_name of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._file_from_content_name = file_from_content_name - - @property - def template(self): - """Gets the template of this SignRequestQuickCreate. # noqa: E501 - - - :return: The template of this SignRequestQuickCreate. # noqa: E501 - :rtype: str - """ - return self._template - - @template.setter - def template(self, template): - """Sets the template of this SignRequestQuickCreate. - - - :param template: The template of this SignRequestQuickCreate. # noqa: E501 - :type: str - """ - - self._template = template - - @property - def prefill_tags(self): - """Gets the prefill_tags of this SignRequestQuickCreate. # noqa: E501 - - Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 - - :return: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 - :rtype: list[InlinePrefillTags] - """ - return self._prefill_tags - - @prefill_tags.setter - def prefill_tags(self, prefill_tags): - """Sets the prefill_tags of this SignRequestQuickCreate. - - Prefill signer input data, see [prefill tags](#section/Preparing-a-document/Prefill-tags-templates) # noqa: E501 - - :param prefill_tags: The prefill_tags of this SignRequestQuickCreate. # noqa: E501 - :type: list[InlinePrefillTags] - """ - - self._prefill_tags = prefill_tags - - @property - def integrations(self): - """Gets the integrations of this SignRequestQuickCreate. # noqa: E501 - - - :return: The integrations of this SignRequestQuickCreate. # noqa: E501 - :rtype: list[InlineIntegrationData] - """ - return self._integrations - - @integrations.setter - def integrations(self, integrations): - """Sets the integrations of this SignRequestQuickCreate. - - - :param integrations: The integrations of this SignRequestQuickCreate. # noqa: E501 - :type: list[InlineIntegrationData] - """ - - self._integrations = integrations - - @property - def file_from_sf(self): - """Gets the file_from_sf of this SignRequestQuickCreate. # noqa: E501 - - - :return: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 - :rtype: FileFromSf - """ - return self._file_from_sf - - @file_from_sf.setter - def file_from_sf(self, file_from_sf): - """Sets the file_from_sf of this SignRequestQuickCreate. - - - :param file_from_sf: The file_from_sf of this SignRequestQuickCreate. # noqa: E501 - :type: FileFromSf - """ - - self._file_from_sf = file_from_sf - - @property - def auto_delete_days(self): - """Gets the auto_delete_days of this SignRequestQuickCreate. # noqa: E501 - - Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :return: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 - :rtype: int - """ - return self._auto_delete_days - - @auto_delete_days.setter - def auto_delete_days(self, auto_delete_days): - """Sets the auto_delete_days of this SignRequestQuickCreate. - - Number of days after which a finished document (signed/cancelled/declined) will be automatically deleted # noqa: E501 - - :param auto_delete_days: The auto_delete_days of this SignRequestQuickCreate. # noqa: E501 - :type: int - """ - if auto_delete_days is not None and auto_delete_days > 730: # noqa: E501 - raise ValueError("Invalid value for `auto_delete_days`, must be a value less than or equal to `730`") # noqa: E501 - if auto_delete_days is not None and auto_delete_days < 1: # noqa: E501 - raise ValueError("Invalid value for `auto_delete_days`, must be a value greater than or equal to `1`") # noqa: E501 - - self._auto_delete_days = auto_delete_days - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, SignRequestQuickCreate): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/signer.py b/signrequest_python_client/models/signer.py deleted file mode 100644 index 888fdd1..0000000 --- a/signrequest_python_client/models/signer.py +++ /dev/null @@ -1,985 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.inline_document_signer_integration_data import InlineDocumentSignerIntegrationData # noqa: F401,E501 -from signrequest_python_client.models.signer_attachment import SignerAttachment # noqa: F401,E501 -from signrequest_python_client.models.signer_inputs import SignerInputs # noqa: F401,E501 - - -class Signer(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'email': 'str', - 'display_name': 'str', - 'first_name': 'str', - 'last_name': 'str', - 'email_viewed': 'bool', - 'viewed': 'bool', - 'signed': 'bool', - 'downloaded': 'bool', - 'signed_on': 'datetime', - 'needs_to_sign': 'bool', - 'approve_only': 'bool', - 'notify_only': 'bool', - 'in_person': 'bool', - 'order': 'int', - 'language': 'str', - 'force_language': 'bool', - 'emailed': 'bool', - 'verify_phone_number': 'str', - 'verify_bank_account': 'str', - 'declined': 'bool', - 'declined_on': 'datetime', - 'forwarded': 'str', - 'forwarded_on': 'datetime', - 'forwarded_to_email': 'str', - 'forwarded_reason': 'str', - 'message': 'str', - 'embed_url_user_id': 'str', - 'inputs': 'list[SignerInputs]', - 'embed_url': 'str', - 'attachments': 'list[SignerAttachment]', - 'redirect_url': 'str', - 'after_document': 'str', - 'integrations': 'list[InlineDocumentSignerIntegrationData]' - } - - attribute_map = { - 'email': 'email', - 'display_name': 'display_name', - 'first_name': 'first_name', - 'last_name': 'last_name', - 'email_viewed': 'email_viewed', - 'viewed': 'viewed', - 'signed': 'signed', - 'downloaded': 'downloaded', - 'signed_on': 'signed_on', - 'needs_to_sign': 'needs_to_sign', - 'approve_only': 'approve_only', - 'notify_only': 'notify_only', - 'in_person': 'in_person', - 'order': 'order', - 'language': 'language', - 'force_language': 'force_language', - 'emailed': 'emailed', - 'verify_phone_number': 'verify_phone_number', - 'verify_bank_account': 'verify_bank_account', - 'declined': 'declined', - 'declined_on': 'declined_on', - 'forwarded': 'forwarded', - 'forwarded_on': 'forwarded_on', - 'forwarded_to_email': 'forwarded_to_email', - 'forwarded_reason': 'forwarded_reason', - 'message': 'message', - 'embed_url_user_id': 'embed_url_user_id', - 'inputs': 'inputs', - 'embed_url': 'embed_url', - 'attachments': 'attachments', - 'redirect_url': 'redirect_url', - 'after_document': 'after_document', - 'integrations': 'integrations' - } - - def __init__(self, email=None, display_name=None, first_name=None, last_name=None, email_viewed=None, viewed=None, signed=None, downloaded=None, signed_on=None, needs_to_sign=True, approve_only=None, notify_only=None, in_person=None, order=None, language=None, force_language=None, emailed=None, verify_phone_number=None, verify_bank_account=None, declined=None, declined_on=None, forwarded=None, forwarded_on=None, forwarded_to_email=None, forwarded_reason=None, message=None, embed_url_user_id=None, inputs=None, embed_url=None, attachments=None, redirect_url=None, after_document=None, integrations=None): # noqa: E501 - """Signer - a model defined in Swagger""" # noqa: E501 - - self._email = None - self._display_name = None - self._first_name = None - self._last_name = None - self._email_viewed = None - self._viewed = None - self._signed = None - self._downloaded = None - self._signed_on = None - self._needs_to_sign = None - self._approve_only = None - self._notify_only = None - self._in_person = None - self._order = None - self._language = None - self._force_language = None - self._emailed = None - self._verify_phone_number = None - self._verify_bank_account = None - self._declined = None - self._declined_on = None - self._forwarded = None - self._forwarded_on = None - self._forwarded_to_email = None - self._forwarded_reason = None - self._message = None - self._embed_url_user_id = None - self._inputs = None - self._embed_url = None - self._attachments = None - self._redirect_url = None - self._after_document = None - self._integrations = None - self.discriminator = None - - self.email = email - if display_name is not None: - self.display_name = display_name - if first_name is not None: - self.first_name = first_name - if last_name is not None: - self.last_name = last_name - if email_viewed is not None: - self.email_viewed = email_viewed - if viewed is not None: - self.viewed = viewed - if signed is not None: - self.signed = signed - if downloaded is not None: - self.downloaded = downloaded - if signed_on is not None: - self.signed_on = signed_on - if needs_to_sign is not None: - self.needs_to_sign = needs_to_sign - if approve_only is not None: - self.approve_only = approve_only - if notify_only is not None: - self.notify_only = notify_only - if in_person is not None: - self.in_person = in_person - if order is not None: - self.order = order - if language is not None: - self.language = language - if force_language is not None: - self.force_language = force_language - if emailed is not None: - self.emailed = emailed - if verify_phone_number is not None: - self.verify_phone_number = verify_phone_number - if verify_bank_account is not None: - self.verify_bank_account = verify_bank_account - if declined is not None: - self.declined = declined - if declined_on is not None: - self.declined_on = declined_on - if forwarded is not None: - self.forwarded = forwarded - if forwarded_on is not None: - self.forwarded_on = forwarded_on - if forwarded_to_email is not None: - self.forwarded_to_email = forwarded_to_email - if forwarded_reason is not None: - self.forwarded_reason = forwarded_reason - if message is not None: - self.message = message - if embed_url_user_id is not None: - self.embed_url_user_id = embed_url_user_id - if inputs is not None: - self.inputs = inputs - if embed_url is not None: - self.embed_url = embed_url - if attachments is not None: - self.attachments = attachments - if redirect_url is not None: - self.redirect_url = redirect_url - if after_document is not None: - self.after_document = after_document - if integrations is not None: - self.integrations = integrations - - @property - def email(self): - """Gets the email of this Signer. # noqa: E501 - - - :return: The email of this Signer. # noqa: E501 - :rtype: str - """ - return self._email - - @email.setter - def email(self, email): - """Sets the email of this Signer. - - - :param email: The email of this Signer. # noqa: E501 - :type: str - """ - if email is None: - raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 - if email is not None and len(email) > 255: - raise ValueError("Invalid value for `email`, length must be less than or equal to `255`") # noqa: E501 - if email is not None and len(email) < 1: - raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 - - self._email = email - - @property - def display_name(self): - """Gets the display_name of this Signer. # noqa: E501 - - - :return: The display_name of this Signer. # noqa: E501 - :rtype: str - """ - return self._display_name - - @display_name.setter - def display_name(self, display_name): - """Sets the display_name of this Signer. - - - :param display_name: The display_name of this Signer. # noqa: E501 - :type: str - """ - if display_name is not None and len(display_name) < 1: - raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 - - self._display_name = display_name - - @property - def first_name(self): - """Gets the first_name of this Signer. # noqa: E501 - - - :return: The first_name of this Signer. # noqa: E501 - :rtype: str - """ - return self._first_name - - @first_name.setter - def first_name(self, first_name): - """Sets the first_name of this Signer. - - - :param first_name: The first_name of this Signer. # noqa: E501 - :type: str - """ - if first_name is not None and len(first_name) > 255: - raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 - - self._first_name = first_name - - @property - def last_name(self): - """Gets the last_name of this Signer. # noqa: E501 - - - :return: The last_name of this Signer. # noqa: E501 - :rtype: str - """ - return self._last_name - - @last_name.setter - def last_name(self, last_name): - """Sets the last_name of this Signer. - - - :param last_name: The last_name of this Signer. # noqa: E501 - :type: str - """ - if last_name is not None and len(last_name) > 255: - raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 - - self._last_name = last_name - - @property - def email_viewed(self): - """Gets the email_viewed of this Signer. # noqa: E501 - - - :return: The email_viewed of this Signer. # noqa: E501 - :rtype: bool - """ - return self._email_viewed - - @email_viewed.setter - def email_viewed(self, email_viewed): - """Sets the email_viewed of this Signer. - - - :param email_viewed: The email_viewed of this Signer. # noqa: E501 - :type: bool - """ - - self._email_viewed = email_viewed - - @property - def viewed(self): - """Gets the viewed of this Signer. # noqa: E501 - - - :return: The viewed of this Signer. # noqa: E501 - :rtype: bool - """ - return self._viewed - - @viewed.setter - def viewed(self, viewed): - """Sets the viewed of this Signer. - - - :param viewed: The viewed of this Signer. # noqa: E501 - :type: bool - """ - - self._viewed = viewed - - @property - def signed(self): - """Gets the signed of this Signer. # noqa: E501 - - - :return: The signed of this Signer. # noqa: E501 - :rtype: bool - """ - return self._signed - - @signed.setter - def signed(self, signed): - """Sets the signed of this Signer. - - - :param signed: The signed of this Signer. # noqa: E501 - :type: bool - """ - - self._signed = signed - - @property - def downloaded(self): - """Gets the downloaded of this Signer. # noqa: E501 - - - :return: The downloaded of this Signer. # noqa: E501 - :rtype: bool - """ - return self._downloaded - - @downloaded.setter - def downloaded(self, downloaded): - """Sets the downloaded of this Signer. - - - :param downloaded: The downloaded of this Signer. # noqa: E501 - :type: bool - """ - - self._downloaded = downloaded - - @property - def signed_on(self): - """Gets the signed_on of this Signer. # noqa: E501 - - - :return: The signed_on of this Signer. # noqa: E501 - :rtype: datetime - """ - return self._signed_on - - @signed_on.setter - def signed_on(self, signed_on): - """Sets the signed_on of this Signer. - - - :param signed_on: The signed_on of this Signer. # noqa: E501 - :type: datetime - """ - - self._signed_on = signed_on - - @property - def needs_to_sign(self): - """Gets the needs_to_sign of this Signer. # noqa: E501 - - - :return: The needs_to_sign of this Signer. # noqa: E501 - :rtype: bool - """ - return self._needs_to_sign - - @needs_to_sign.setter - def needs_to_sign(self, needs_to_sign): - """Sets the needs_to_sign of this Signer. - - - :param needs_to_sign: The needs_to_sign of this Signer. # noqa: E501 - :type: bool - """ - - self._needs_to_sign = needs_to_sign - - @property - def approve_only(self): - """Gets the approve_only of this Signer. # noqa: E501 - - - :return: The approve_only of this Signer. # noqa: E501 - :rtype: bool - """ - return self._approve_only - - @approve_only.setter - def approve_only(self, approve_only): - """Sets the approve_only of this Signer. - - - :param approve_only: The approve_only of this Signer. # noqa: E501 - :type: bool - """ - - self._approve_only = approve_only - - @property - def notify_only(self): - """Gets the notify_only of this Signer. # noqa: E501 - - - :return: The notify_only of this Signer. # noqa: E501 - :rtype: bool - """ - return self._notify_only - - @notify_only.setter - def notify_only(self, notify_only): - """Sets the notify_only of this Signer. - - - :param notify_only: The notify_only of this Signer. # noqa: E501 - :type: bool - """ - - self._notify_only = notify_only - - @property - def in_person(self): - """Gets the in_person of this Signer. # noqa: E501 - - - :return: The in_person of this Signer. # noqa: E501 - :rtype: bool - """ - return self._in_person - - @in_person.setter - def in_person(self, in_person): - """Sets the in_person of this Signer. - - - :param in_person: The in_person of this Signer. # noqa: E501 - :type: bool - """ - - self._in_person = in_person - - @property - def order(self): - """Gets the order of this Signer. # noqa: E501 - - - :return: The order of this Signer. # noqa: E501 - :rtype: int - """ - return self._order - - @order.setter - def order(self, order): - """Sets the order of this Signer. - - - :param order: The order of this Signer. # noqa: E501 - :type: int - """ - if order is not None and order > 2147483647: # noqa: E501 - raise ValueError("Invalid value for `order`, must be a value less than or equal to `2147483647`") # noqa: E501 - if order is not None and order < 0: # noqa: E501 - raise ValueError("Invalid value for `order`, must be a value greater than or equal to `0`") # noqa: E501 - - self._order = order - - @property - def language(self): - """Gets the language of this Signer. # noqa: E501 - - - :return: The language of this Signer. # noqa: E501 - :rtype: str - """ - return self._language - - @language.setter - def language(self, language): - """Sets the language of this Signer. - - - :param language: The language of this Signer. # noqa: E501 - :type: str - """ - allowed_values = ["en", "en-gb", "nl", "fr", "de", "he", "da", "fi", "hu", "it", "no", "pl", "pt", "es", "sv", "ru"] # noqa: E501 - if language not in allowed_values: - raise ValueError( - "Invalid value for `language` ({0}), must be one of {1}" # noqa: E501 - .format(language, allowed_values) - ) - - self._language = language - - @property - def force_language(self): - """Gets the force_language of this Signer. # noqa: E501 - - - :return: The force_language of this Signer. # noqa: E501 - :rtype: bool - """ - return self._force_language - - @force_language.setter - def force_language(self, force_language): - """Sets the force_language of this Signer. - - - :param force_language: The force_language of this Signer. # noqa: E501 - :type: bool - """ - - self._force_language = force_language - - @property - def emailed(self): - """Gets the emailed of this Signer. # noqa: E501 - - - :return: The emailed of this Signer. # noqa: E501 - :rtype: bool - """ - return self._emailed - - @emailed.setter - def emailed(self, emailed): - """Sets the emailed of this Signer. - - - :param emailed: The emailed of this Signer. # noqa: E501 - :type: bool - """ - - self._emailed = emailed - - @property - def verify_phone_number(self): - """Gets the verify_phone_number of this Signer. # noqa: E501 - - - :return: The verify_phone_number of this Signer. # noqa: E501 - :rtype: str - """ - return self._verify_phone_number - - @verify_phone_number.setter - def verify_phone_number(self, verify_phone_number): - """Sets the verify_phone_number of this Signer. - - - :param verify_phone_number: The verify_phone_number of this Signer. # noqa: E501 - :type: str - """ - if verify_phone_number is not None and len(verify_phone_number) > 255: - raise ValueError("Invalid value for `verify_phone_number`, length must be less than or equal to `255`") # noqa: E501 - - self._verify_phone_number = verify_phone_number - - @property - def verify_bank_account(self): - """Gets the verify_bank_account of this Signer. # noqa: E501 - - - :return: The verify_bank_account of this Signer. # noqa: E501 - :rtype: str - """ - return self._verify_bank_account - - @verify_bank_account.setter - def verify_bank_account(self, verify_bank_account): - """Sets the verify_bank_account of this Signer. - - - :param verify_bank_account: The verify_bank_account of this Signer. # noqa: E501 - :type: str - """ - if verify_bank_account is not None and len(verify_bank_account) > 255: - raise ValueError("Invalid value for `verify_bank_account`, length must be less than or equal to `255`") # noqa: E501 - - self._verify_bank_account = verify_bank_account - - @property - def declined(self): - """Gets the declined of this Signer. # noqa: E501 - - - :return: The declined of this Signer. # noqa: E501 - :rtype: bool - """ - return self._declined - - @declined.setter - def declined(self, declined): - """Sets the declined of this Signer. - - - :param declined: The declined of this Signer. # noqa: E501 - :type: bool - """ - - self._declined = declined - - @property - def declined_on(self): - """Gets the declined_on of this Signer. # noqa: E501 - - - :return: The declined_on of this Signer. # noqa: E501 - :rtype: datetime - """ - return self._declined_on - - @declined_on.setter - def declined_on(self, declined_on): - """Sets the declined_on of this Signer. - - - :param declined_on: The declined_on of this Signer. # noqa: E501 - :type: datetime - """ - - self._declined_on = declined_on - - @property - def forwarded(self): - """Gets the forwarded of this Signer. # noqa: E501 - - - :return: The forwarded of this Signer. # noqa: E501 - :rtype: str - """ - return self._forwarded - - @forwarded.setter - def forwarded(self, forwarded): - """Sets the forwarded of this Signer. - - - :param forwarded: The forwarded of this Signer. # noqa: E501 - :type: str - """ - - self._forwarded = forwarded - - @property - def forwarded_on(self): - """Gets the forwarded_on of this Signer. # noqa: E501 - - - :return: The forwarded_on of this Signer. # noqa: E501 - :rtype: datetime - """ - return self._forwarded_on - - @forwarded_on.setter - def forwarded_on(self, forwarded_on): - """Sets the forwarded_on of this Signer. - - - :param forwarded_on: The forwarded_on of this Signer. # noqa: E501 - :type: datetime - """ - - self._forwarded_on = forwarded_on - - @property - def forwarded_to_email(self): - """Gets the forwarded_to_email of this Signer. # noqa: E501 - - - :return: The forwarded_to_email of this Signer. # noqa: E501 - :rtype: str - """ - return self._forwarded_to_email - - @forwarded_to_email.setter - def forwarded_to_email(self, forwarded_to_email): - """Sets the forwarded_to_email of this Signer. - - - :param forwarded_to_email: The forwarded_to_email of this Signer. # noqa: E501 - :type: str - """ - if forwarded_to_email is not None and len(forwarded_to_email) < 1: - raise ValueError("Invalid value for `forwarded_to_email`, length must be greater than or equal to `1`") # noqa: E501 - - self._forwarded_to_email = forwarded_to_email - - @property - def forwarded_reason(self): - """Gets the forwarded_reason of this Signer. # noqa: E501 - - - :return: The forwarded_reason of this Signer. # noqa: E501 - :rtype: str - """ - return self._forwarded_reason - - @forwarded_reason.setter - def forwarded_reason(self, forwarded_reason): - """Sets the forwarded_reason of this Signer. - - - :param forwarded_reason: The forwarded_reason of this Signer. # noqa: E501 - :type: str - """ - if forwarded_reason is not None and len(forwarded_reason) < 1: - raise ValueError("Invalid value for `forwarded_reason`, length must be greater than or equal to `1`") # noqa: E501 - - self._forwarded_reason = forwarded_reason - - @property - def message(self): - """Gets the message of this Signer. # noqa: E501 - - - :return: The message of this Signer. # noqa: E501 - :rtype: str - """ - return self._message - - @message.setter - def message(self, message): - """Sets the message of this Signer. - - - :param message: The message of this Signer. # noqa: E501 - :type: str - """ - if message is not None and len(message) < 1: - raise ValueError("Invalid value for `message`, length must be greater than or equal to `1`") # noqa: E501 - - self._message = message - - @property - def embed_url_user_id(self): - """Gets the embed_url_user_id of this Signer. # noqa: E501 - - - :return: The embed_url_user_id of this Signer. # noqa: E501 - :rtype: str - """ - return self._embed_url_user_id - - @embed_url_user_id.setter - def embed_url_user_id(self, embed_url_user_id): - """Sets the embed_url_user_id of this Signer. - - - :param embed_url_user_id: The embed_url_user_id of this Signer. # noqa: E501 - :type: str - """ - if embed_url_user_id is not None and len(embed_url_user_id) > 255: - raise ValueError("Invalid value for `embed_url_user_id`, length must be less than or equal to `255`") # noqa: E501 - - self._embed_url_user_id = embed_url_user_id - - @property - def inputs(self): - """Gets the inputs of this Signer. # noqa: E501 - - - :return: The inputs of this Signer. # noqa: E501 - :rtype: list[SignerInputs] - """ - return self._inputs - - @inputs.setter - def inputs(self, inputs): - """Sets the inputs of this Signer. - - - :param inputs: The inputs of this Signer. # noqa: E501 - :type: list[SignerInputs] - """ - - self._inputs = inputs - - @property - def embed_url(self): - """Gets the embed_url of this Signer. # noqa: E501 - - - :return: The embed_url of this Signer. # noqa: E501 - :rtype: str - """ - return self._embed_url - - @embed_url.setter - def embed_url(self, embed_url): - """Sets the embed_url of this Signer. - - - :param embed_url: The embed_url of this Signer. # noqa: E501 - :type: str - """ - if embed_url is not None and len(embed_url) < 1: - raise ValueError("Invalid value for `embed_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._embed_url = embed_url - - @property - def attachments(self): - """Gets the attachments of this Signer. # noqa: E501 - - - :return: The attachments of this Signer. # noqa: E501 - :rtype: list[SignerAttachment] - """ - return self._attachments - - @attachments.setter - def attachments(self, attachments): - """Sets the attachments of this Signer. - - - :param attachments: The attachments of this Signer. # noqa: E501 - :type: list[SignerAttachment] - """ - - self._attachments = attachments - - @property - def redirect_url(self): - """Gets the redirect_url of this Signer. # noqa: E501 - - - :return: The redirect_url of this Signer. # noqa: E501 - :rtype: str - """ - return self._redirect_url - - @redirect_url.setter - def redirect_url(self, redirect_url): - """Sets the redirect_url of this Signer. - - - :param redirect_url: The redirect_url of this Signer. # noqa: E501 - :type: str - """ - if redirect_url is not None and len(redirect_url) > 2100: - raise ValueError("Invalid value for `redirect_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._redirect_url = redirect_url - - @property - def after_document(self): - """Gets the after_document of this Signer. # noqa: E501 - - - :return: The after_document of this Signer. # noqa: E501 - :rtype: str - """ - return self._after_document - - @after_document.setter - def after_document(self, after_document): - """Sets the after_document of this Signer. - - - :param after_document: The after_document of this Signer. # noqa: E501 - :type: str - """ - - self._after_document = after_document - - @property - def integrations(self): - """Gets the integrations of this Signer. # noqa: E501 - - - :return: The integrations of this Signer. # noqa: E501 - :rtype: list[InlineDocumentSignerIntegrationData] - """ - return self._integrations - - @integrations.setter - def integrations(self, integrations): - """Sets the integrations of this Signer. - - - :param integrations: The integrations of this Signer. # noqa: E501 - :type: list[InlineDocumentSignerIntegrationData] - """ - - self._integrations = integrations - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Signer): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/signer_attachment.py b/signrequest_python_client/models/signer_attachment.py deleted file mode 100644 index 4a74c9a..0000000 --- a/signrequest_python_client/models/signer_attachment.py +++ /dev/null @@ -1,198 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.required_attachment import RequiredAttachment # noqa: F401,E501 - - -class SignerAttachment(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'uuid': 'str', - 'name': 'str', - 'file': 'str', - 'for_attachment': 'RequiredAttachment' - } - - attribute_map = { - 'uuid': 'uuid', - 'name': 'name', - 'file': 'file', - 'for_attachment': 'for_attachment' - } - - def __init__(self, uuid=None, name=None, file=None, for_attachment=None): # noqa: E501 - """SignerAttachment - a model defined in Swagger""" # noqa: E501 - - self._uuid = None - self._name = None - self._file = None - self._for_attachment = None - self.discriminator = None - - if uuid is not None: - self.uuid = uuid - if name is not None: - self.name = name - if file is not None: - self.file = file - if for_attachment is not None: - self.for_attachment = for_attachment - - @property - def uuid(self): - """Gets the uuid of this SignerAttachment. # noqa: E501 - - - :return: The uuid of this SignerAttachment. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this SignerAttachment. - - - :param uuid: The uuid of this SignerAttachment. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def name(self): - """Gets the name of this SignerAttachment. # noqa: E501 - - Defaults to filename # noqa: E501 - - :return: The name of this SignerAttachment. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this SignerAttachment. - - Defaults to filename # noqa: E501 - - :param name: The name of this SignerAttachment. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def file(self): - """Gets the file of this SignerAttachment. # noqa: E501 - - - :return: The file of this SignerAttachment. # noqa: E501 - :rtype: str - """ - return self._file - - @file.setter - def file(self, file): - """Sets the file of this SignerAttachment. - - - :param file: The file of this SignerAttachment. # noqa: E501 - :type: str - """ - - self._file = file - - @property - def for_attachment(self): - """Gets the for_attachment of this SignerAttachment. # noqa: E501 - - - :return: The for_attachment of this SignerAttachment. # noqa: E501 - :rtype: RequiredAttachment - """ - return self._for_attachment - - @for_attachment.setter - def for_attachment(self, for_attachment): - """Sets the for_attachment of this SignerAttachment. - - - :param for_attachment: The for_attachment of this SignerAttachment. # noqa: E501 - :type: RequiredAttachment - """ - - self._for_attachment = for_attachment - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, SignerAttachment): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/signer_inputs.py b/signrequest_python_client/models/signer_inputs.py deleted file mode 100644 index efbe89c..0000000 --- a/signrequest_python_client/models/signer_inputs.py +++ /dev/null @@ -1,279 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class SignerInputs(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'type': 'str', - 'page_index': 'int', - 'text': 'str', - 'checkbox_value': 'bool', - 'date_value': 'date', - 'external_id': 'str', - 'placeholder_uuid': 'str' - } - - attribute_map = { - 'type': 'type', - 'page_index': 'page_index', - 'text': 'text', - 'checkbox_value': 'checkbox_value', - 'date_value': 'date_value', - 'external_id': 'external_id', - 'placeholder_uuid': 'placeholder_uuid' - } - - def __init__(self, type=None, page_index=None, text=None, checkbox_value=None, date_value=None, external_id=None, placeholder_uuid=None): # noqa: E501 - """SignerInputs - a model defined in Swagger""" # noqa: E501 - - self._type = None - self._page_index = None - self._text = None - self._checkbox_value = None - self._date_value = None - self._external_id = None - self._placeholder_uuid = None - self.discriminator = None - - if type is not None: - self.type = type - self.page_index = page_index - if text is not None: - self.text = text - if checkbox_value is not None: - self.checkbox_value = checkbox_value - if date_value is not None: - self.date_value = date_value - if external_id is not None: - self.external_id = external_id - if placeholder_uuid is not None: - self.placeholder_uuid = placeholder_uuid - - @property - def type(self): - """Gets the type of this SignerInputs. # noqa: E501 - - - :return: The type of this SignerInputs. # noqa: E501 - :rtype: str - """ - return self._type - - @type.setter - def type(self, type): - """Sets the type of this SignerInputs. - - - :param type: The type of this SignerInputs. # noqa: E501 - :type: str - """ - allowed_values = ["s", "i", "n", "d", "t", "c"] # noqa: E501 - if type not in allowed_values: - raise ValueError( - "Invalid value for `type` ({0}), must be one of {1}" # noqa: E501 - .format(type, allowed_values) - ) - - self._type = type - - @property - def page_index(self): - """Gets the page_index of this SignerInputs. # noqa: E501 - - - :return: The page_index of this SignerInputs. # noqa: E501 - :rtype: int - """ - return self._page_index - - @page_index.setter - def page_index(self, page_index): - """Sets the page_index of this SignerInputs. - - - :param page_index: The page_index of this SignerInputs. # noqa: E501 - :type: int - """ - if page_index is None: - raise ValueError("Invalid value for `page_index`, must not be `None`") # noqa: E501 - - self._page_index = page_index - - @property - def text(self): - """Gets the text of this SignerInputs. # noqa: E501 - - - :return: The text of this SignerInputs. # noqa: E501 - :rtype: str - """ - return self._text - - @text.setter - def text(self, text): - """Sets the text of this SignerInputs. - - - :param text: The text of this SignerInputs. # noqa: E501 - :type: str - """ - - self._text = text - - @property - def checkbox_value(self): - """Gets the checkbox_value of this SignerInputs. # noqa: E501 - - - :return: The checkbox_value of this SignerInputs. # noqa: E501 - :rtype: bool - """ - return self._checkbox_value - - @checkbox_value.setter - def checkbox_value(self, checkbox_value): - """Sets the checkbox_value of this SignerInputs. - - - :param checkbox_value: The checkbox_value of this SignerInputs. # noqa: E501 - :type: bool - """ - - self._checkbox_value = checkbox_value - - @property - def date_value(self): - """Gets the date_value of this SignerInputs. # noqa: E501 - - - :return: The date_value of this SignerInputs. # noqa: E501 - :rtype: date - """ - return self._date_value - - @date_value.setter - def date_value(self, date_value): - """Sets the date_value of this SignerInputs. - - - :param date_value: The date_value of this SignerInputs. # noqa: E501 - :type: date - """ - - self._date_value = date_value - - @property - def external_id(self): - """Gets the external_id of this SignerInputs. # noqa: E501 - - - :return: The external_id of this SignerInputs. # noqa: E501 - :rtype: str - """ - return self._external_id - - @external_id.setter - def external_id(self, external_id): - """Sets the external_id of this SignerInputs. - - - :param external_id: The external_id of this SignerInputs. # noqa: E501 - :type: str - """ - if external_id is not None and len(external_id) > 255: - raise ValueError("Invalid value for `external_id`, length must be less than or equal to `255`") # noqa: E501 - - self._external_id = external_id - - @property - def placeholder_uuid(self): - """Gets the placeholder_uuid of this SignerInputs. # noqa: E501 - - - :return: The placeholder_uuid of this SignerInputs. # noqa: E501 - :rtype: str - """ - return self._placeholder_uuid - - @placeholder_uuid.setter - def placeholder_uuid(self, placeholder_uuid): - """Sets the placeholder_uuid of this SignerInputs. - - - :param placeholder_uuid: The placeholder_uuid of this SignerInputs. # noqa: E501 - :type: str - """ - if placeholder_uuid is not None and len(placeholder_uuid) > 36: - raise ValueError("Invalid value for `placeholder_uuid`, length must be less than or equal to `36`") # noqa: E501 - - self._placeholder_uuid = placeholder_uuid - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, SignerInputs): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/signing_log.py b/signrequest_python_client/models/signing_log.py deleted file mode 100644 index 6300f28..0000000 --- a/signrequest_python_client/models/signing_log.py +++ /dev/null @@ -1,144 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class SigningLog(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'pdf': 'str', - 'security_hash': 'str' - } - - attribute_map = { - 'pdf': 'pdf', - 'security_hash': 'security_hash' - } - - def __init__(self, pdf=None, security_hash=None): # noqa: E501 - """SigningLog - a model defined in Swagger""" # noqa: E501 - - self._pdf = None - self._security_hash = None - self.discriminator = None - - if pdf is not None: - self.pdf = pdf - if security_hash is not None: - self.security_hash = security_hash - - @property - def pdf(self): - """Gets the pdf of this SigningLog. # noqa: E501 - - Temporary URL to signing log, expires in five minutes # noqa: E501 - - :return: The pdf of this SigningLog. # noqa: E501 - :rtype: str - """ - return self._pdf - - @pdf.setter - def pdf(self, pdf): - """Sets the pdf of this SigningLog. - - Temporary URL to signing log, expires in five minutes # noqa: E501 - - :param pdf: The pdf of this SigningLog. # noqa: E501 - :type: str - """ - - self._pdf = pdf - - @property - def security_hash(self): - """Gets the security_hash of this SigningLog. # noqa: E501 - - SHA256 hash of PDF contents # noqa: E501 - - :return: The security_hash of this SigningLog. # noqa: E501 - :rtype: str - """ - return self._security_hash - - @security_hash.setter - def security_hash(self, security_hash): - """Sets the security_hash of this SigningLog. - - SHA256 hash of PDF contents # noqa: E501 - - :param security_hash: The security_hash of this SigningLog. # noqa: E501 - :type: str - """ - if security_hash is not None and len(security_hash) < 1: - raise ValueError("Invalid value for `security_hash`, length must be greater than or equal to `1`") # noqa: E501 - - self._security_hash = security_hash - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, SigningLog): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/team.py b/signrequest_python_client/models/team.py deleted file mode 100644 index 3f3fcb7..0000000 --- a/signrequest_python_client/models/team.py +++ /dev/null @@ -1,312 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.inline_team_member import InlineTeamMember # noqa: F401,E501 - - -class Team(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'name': 'str', - 'subdomain': 'str', - 'url': 'str', - 'logo': 'str', - 'phone': 'str', - 'primary_color': 'str', - 'events_callback_url': 'str', - 'members': 'list[InlineTeamMember]' - } - - attribute_map = { - 'name': 'name', - 'subdomain': 'subdomain', - 'url': 'url', - 'logo': 'logo', - 'phone': 'phone', - 'primary_color': 'primary_color', - 'events_callback_url': 'events_callback_url', - 'members': 'members' - } - - def __init__(self, name=None, subdomain=None, url=None, logo=None, phone=None, primary_color=None, events_callback_url=None, members=None): # noqa: E501 - """Team - a model defined in Swagger""" # noqa: E501 - - self._name = None - self._subdomain = None - self._url = None - self._logo = None - self._phone = None - self._primary_color = None - self._events_callback_url = None - self._members = None - self.discriminator = None - - self.name = name - self.subdomain = subdomain - if url is not None: - self.url = url - if logo is not None: - self.logo = logo - if phone is not None: - self.phone = phone - if primary_color is not None: - self.primary_color = primary_color - if events_callback_url is not None: - self.events_callback_url = events_callback_url - if members is not None: - self.members = members - - @property - def name(self): - """Gets the name of this Team. # noqa: E501 - - - :return: The name of this Team. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this Team. - - - :param name: The name of this Team. # noqa: E501 - :type: str - """ - if name is None: - raise ValueError("Invalid value for `name`, must not be `None`") # noqa: E501 - if name is not None and len(name) > 100: - raise ValueError("Invalid value for `name`, length must be less than or equal to `100`") # noqa: E501 - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def subdomain(self): - """Gets the subdomain of this Team. # noqa: E501 - - - :return: The subdomain of this Team. # noqa: E501 - :rtype: str - """ - return self._subdomain - - @subdomain.setter - def subdomain(self, subdomain): - """Sets the subdomain of this Team. - - - :param subdomain: The subdomain of this Team. # noqa: E501 - :type: str - """ - if subdomain is None: - raise ValueError("Invalid value for `subdomain`, must not be `None`") # noqa: E501 - if subdomain is not None and len(subdomain) > 100: - raise ValueError("Invalid value for `subdomain`, length must be less than or equal to `100`") # noqa: E501 - if subdomain is not None and len(subdomain) < 1: - raise ValueError("Invalid value for `subdomain`, length must be greater than or equal to `1`") # noqa: E501 - - self._subdomain = subdomain - - @property - def url(self): - """Gets the url of this Team. # noqa: E501 - - - :return: The url of this Team. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this Team. - - - :param url: The url of this Team. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def logo(self): - """Gets the logo of this Team. # noqa: E501 - - - :return: The logo of this Team. # noqa: E501 - :rtype: str - """ - return self._logo - - @logo.setter - def logo(self, logo): - """Sets the logo of this Team. - - - :param logo: The logo of this Team. # noqa: E501 - :type: str - """ - - self._logo = logo - - @property - def phone(self): - """Gets the phone of this Team. # noqa: E501 - - - :return: The phone of this Team. # noqa: E501 - :rtype: str - """ - return self._phone - - @phone.setter - def phone(self, phone): - """Sets the phone of this Team. - - - :param phone: The phone of this Team. # noqa: E501 - :type: str - """ - if phone is not None and len(phone) > 100: - raise ValueError("Invalid value for `phone`, length must be less than or equal to `100`") # noqa: E501 - - self._phone = phone - - @property - def primary_color(self): - """Gets the primary_color of this Team. # noqa: E501 - - - :return: The primary_color of this Team. # noqa: E501 - :rtype: str - """ - return self._primary_color - - @primary_color.setter - def primary_color(self, primary_color): - """Sets the primary_color of this Team. - - - :param primary_color: The primary_color of this Team. # noqa: E501 - :type: str - """ - if primary_color is not None and len(primary_color) > 100: - raise ValueError("Invalid value for `primary_color`, length must be less than or equal to `100`") # noqa: E501 - - self._primary_color = primary_color - - @property - def events_callback_url(self): - """Gets the events_callback_url of this Team. # noqa: E501 - - - :return: The events_callback_url of this Team. # noqa: E501 - :rtype: str - """ - return self._events_callback_url - - @events_callback_url.setter - def events_callback_url(self, events_callback_url): - """Sets the events_callback_url of this Team. - - - :param events_callback_url: The events_callback_url of this Team. # noqa: E501 - :type: str - """ - if events_callback_url is not None and len(events_callback_url) > 2100: - raise ValueError("Invalid value for `events_callback_url`, length must be less than or equal to `2100`") # noqa: E501 - - self._events_callback_url = events_callback_url - - @property - def members(self): - """Gets the members of this Team. # noqa: E501 - - - :return: The members of this Team. # noqa: E501 - :rtype: list[InlineTeamMember] - """ - return self._members - - @members.setter - def members(self, members): - """Sets the members of this Team. - - - :param members: The members of this Team. # noqa: E501 - :type: list[InlineTeamMember] - """ - - self._members = members - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Team): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/team_member.py b/signrequest_python_client/models/team_member.py deleted file mode 100644 index 8f66a65..0000000 --- a/signrequest_python_client/models/team_member.py +++ /dev/null @@ -1,246 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.user import User # noqa: F401,E501 - - -class TeamMember(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'uuid': 'str', - 'url': 'str', - 'user': 'User', - 'is_admin': 'bool', - 'is_active': 'bool', - 'is_owner': 'bool' - } - - attribute_map = { - 'uuid': 'uuid', - 'url': 'url', - 'user': 'user', - 'is_admin': 'is_admin', - 'is_active': 'is_active', - 'is_owner': 'is_owner' - } - - def __init__(self, uuid=None, url=None, user=None, is_admin=None, is_active=None, is_owner=None): # noqa: E501 - """TeamMember - a model defined in Swagger""" # noqa: E501 - - self._uuid = None - self._url = None - self._user = None - self._is_admin = None - self._is_active = None - self._is_owner = None - self.discriminator = None - - if uuid is not None: - self.uuid = uuid - if url is not None: - self.url = url - if user is not None: - self.user = user - if is_admin is not None: - self.is_admin = is_admin - if is_active is not None: - self.is_active = is_active - if is_owner is not None: - self.is_owner = is_owner - - @property - def uuid(self): - """Gets the uuid of this TeamMember. # noqa: E501 - - - :return: The uuid of this TeamMember. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this TeamMember. - - - :param uuid: The uuid of this TeamMember. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def url(self): - """Gets the url of this TeamMember. # noqa: E501 - - - :return: The url of this TeamMember. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this TeamMember. - - - :param url: The url of this TeamMember. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def user(self): - """Gets the user of this TeamMember. # noqa: E501 - - - :return: The user of this TeamMember. # noqa: E501 - :rtype: User - """ - return self._user - - @user.setter - def user(self, user): - """Sets the user of this TeamMember. - - - :param user: The user of this TeamMember. # noqa: E501 - :type: User - """ - - self._user = user - - @property - def is_admin(self): - """Gets the is_admin of this TeamMember. # noqa: E501 - - - :return: The is_admin of this TeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_admin - - @is_admin.setter - def is_admin(self, is_admin): - """Sets the is_admin of this TeamMember. - - - :param is_admin: The is_admin of this TeamMember. # noqa: E501 - :type: bool - """ - - self._is_admin = is_admin - - @property - def is_active(self): - """Gets the is_active of this TeamMember. # noqa: E501 - - - :return: The is_active of this TeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_active - - @is_active.setter - def is_active(self, is_active): - """Sets the is_active of this TeamMember. - - - :param is_active: The is_active of this TeamMember. # noqa: E501 - :type: bool - """ - - self._is_active = is_active - - @property - def is_owner(self): - """Gets the is_owner of this TeamMember. # noqa: E501 - - - :return: The is_owner of this TeamMember. # noqa: E501 - :rtype: bool - """ - return self._is_owner - - @is_owner.setter - def is_owner(self, is_owner): - """Sets the is_owner of this TeamMember. - - - :param is_owner: The is_owner of this TeamMember. # noqa: E501 - :type: bool - """ - - self._is_owner = is_owner - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, TeamMember): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/template.py b/signrequest_python_client/models/template.py deleted file mode 100644 index ae6a84d..0000000 --- a/signrequest_python_client/models/template.py +++ /dev/null @@ -1,259 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - -from signrequest_python_client.models.document_signer_template_conf import DocumentSignerTemplateConf # noqa: F401,E501 -from signrequest_python_client.models.user import User # noqa: F401,E501 - - -class Template(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'url': 'str', - 'name': 'str', - 'uuid': 'str', - 'user': 'User', - 'who': 'str', - 'signers': 'list[DocumentSignerTemplateConf]' - } - - attribute_map = { - 'url': 'url', - 'name': 'name', - 'uuid': 'uuid', - 'user': 'user', - 'who': 'who', - 'signers': 'signers' - } - - def __init__(self, url=None, name=None, uuid=None, user=None, who=None, signers=None): # noqa: E501 - """Template - a model defined in Swagger""" # noqa: E501 - - self._url = None - self._name = None - self._uuid = None - self._user = None - self._who = None - self._signers = None - self.discriminator = None - - if url is not None: - self.url = url - if name is not None: - self.name = name - if uuid is not None: - self.uuid = uuid - if user is not None: - self.user = user - if who is not None: - self.who = who - if signers is not None: - self.signers = signers - - @property - def url(self): - """Gets the url of this Template. # noqa: E501 - - - :return: The url of this Template. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this Template. - - - :param url: The url of this Template. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def name(self): - """Gets the name of this Template. # noqa: E501 - - Defaults to filename # noqa: E501 - - :return: The name of this Template. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this Template. - - Defaults to filename # noqa: E501 - - :param name: The name of this Template. # noqa: E501 - :type: str - """ - if name is not None and len(name) < 1: - raise ValueError("Invalid value for `name`, length must be greater than or equal to `1`") # noqa: E501 - - self._name = name - - @property - def uuid(self): - """Gets the uuid of this Template. # noqa: E501 - - - :return: The uuid of this Template. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this Template. - - - :param uuid: The uuid of this Template. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def user(self): - """Gets the user of this Template. # noqa: E501 - - - :return: The user of this Template. # noqa: E501 - :rtype: User - """ - return self._user - - @user.setter - def user(self, user): - """Sets the user of this Template. - - - :param user: The user of this Template. # noqa: E501 - :type: User - """ - - self._user = user - - @property - def who(self): - """Gets the who of this Template. # noqa: E501 - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :return: The who of this Template. # noqa: E501 - :rtype: str - """ - return self._who - - @who.setter - def who(self, who): - """Sets the who of this Template. - - `m`: only me, `mo`: me and others, `o`: only others # noqa: E501 - - :param who: The who of this Template. # noqa: E501 - :type: str - """ - allowed_values = ["m", "mo", "o"] # noqa: E501 - if who not in allowed_values: - raise ValueError( - "Invalid value for `who` ({0}), must be one of {1}" # noqa: E501 - .format(who, allowed_values) - ) - - self._who = who - - @property - def signers(self): - """Gets the signers of this Template. # noqa: E501 - - - :return: The signers of this Template. # noqa: E501 - :rtype: list[DocumentSignerTemplateConf] - """ - return self._signers - - @signers.setter - def signers(self, signers): - """Sets the signers of this Template. - - - :param signers: The signers of this Template. # noqa: E501 - :type: list[DocumentSignerTemplateConf] - """ - - self._signers = signers - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, Template): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/user.py b/signrequest_python_client/models/user.py deleted file mode 100644 index 3242acd..0000000 --- a/signrequest_python_client/models/user.py +++ /dev/null @@ -1,201 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class User(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'email': 'str', - 'first_name': 'str', - 'last_name': 'str', - 'display_name': 'str' - } - - attribute_map = { - 'email': 'email', - 'first_name': 'first_name', - 'last_name': 'last_name', - 'display_name': 'display_name' - } - - def __init__(self, email=None, first_name=None, last_name=None, display_name=None): # noqa: E501 - """User - a model defined in Swagger""" # noqa: E501 - - self._email = None - self._first_name = None - self._last_name = None - self._display_name = None - self.discriminator = None - - self.email = email - if first_name is not None: - self.first_name = first_name - if last_name is not None: - self.last_name = last_name - if display_name is not None: - self.display_name = display_name - - @property - def email(self): - """Gets the email of this User. # noqa: E501 - - - :return: The email of this User. # noqa: E501 - :rtype: str - """ - return self._email - - @email.setter - def email(self, email): - """Sets the email of this User. - - - :param email: The email of this User. # noqa: E501 - :type: str - """ - if email is None: - raise ValueError("Invalid value for `email`, must not be `None`") # noqa: E501 - if email is not None and len(email) > 254: - raise ValueError("Invalid value for `email`, length must be less than or equal to `254`") # noqa: E501 - if email is not None and len(email) < 1: - raise ValueError("Invalid value for `email`, length must be greater than or equal to `1`") # noqa: E501 - - self._email = email - - @property - def first_name(self): - """Gets the first_name of this User. # noqa: E501 - - - :return: The first_name of this User. # noqa: E501 - :rtype: str - """ - return self._first_name - - @first_name.setter - def first_name(self, first_name): - """Sets the first_name of this User. - - - :param first_name: The first_name of this User. # noqa: E501 - :type: str - """ - if first_name is not None and len(first_name) > 255: - raise ValueError("Invalid value for `first_name`, length must be less than or equal to `255`") # noqa: E501 - - self._first_name = first_name - - @property - def last_name(self): - """Gets the last_name of this User. # noqa: E501 - - - :return: The last_name of this User. # noqa: E501 - :rtype: str - """ - return self._last_name - - @last_name.setter - def last_name(self, last_name): - """Sets the last_name of this User. - - - :param last_name: The last_name of this User. # noqa: E501 - :type: str - """ - if last_name is not None and len(last_name) > 255: - raise ValueError("Invalid value for `last_name`, length must be less than or equal to `255`") # noqa: E501 - - self._last_name = last_name - - @property - def display_name(self): - """Gets the display_name of this User. # noqa: E501 - - - :return: The display_name of this User. # noqa: E501 - :rtype: str - """ - return self._display_name - - @display_name.setter - def display_name(self, display_name): - """Sets the display_name of this User. - - - :param display_name: The display_name of this User. # noqa: E501 - :type: str - """ - if display_name is not None and len(display_name) < 1: - raise ValueError("Invalid value for `display_name`, length must be greater than or equal to `1`") # noqa: E501 - - self._display_name = display_name - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, User): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/models/webhook_subscription.py b/signrequest_python_client/models/webhook_subscription.py deleted file mode 100644 index bcf0a49..0000000 --- a/signrequest_python_client/models/webhook_subscription.py +++ /dev/null @@ -1,292 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -import pprint -import re # noqa: F401 - -import six - - -class WebhookSubscription(object): - """NOTE: This class is auto generated by the swagger code generator program. - - Do not edit the class manually. - """ - - """ - Attributes: - swagger_types (dict): The key is attribute name - and the value is attribute type. - attribute_map (dict): The key is attribute name - and the value is json key in definition. - """ - swagger_types = { - 'url': 'str', - 'uuid': 'str', - 'name': 'str', - 'event_type': 'str', - 'callback_url': 'str', - 'integration': 'str', - 'created': 'datetime' - } - - attribute_map = { - 'url': 'url', - 'uuid': 'uuid', - 'name': 'name', - 'event_type': 'event_type', - 'callback_url': 'callback_url', - 'integration': 'integration', - 'created': 'created' - } - - def __init__(self, url=None, uuid=None, name=None, event_type=None, callback_url=None, integration=None, created=None): # noqa: E501 - """WebhookSubscription - a model defined in Swagger""" # noqa: E501 - - self._url = None - self._uuid = None - self._name = None - self._event_type = None - self._callback_url = None - self._integration = None - self._created = None - self.discriminator = None - - if url is not None: - self.url = url - if uuid is not None: - self.uuid = uuid - if name is not None: - self.name = name - self.event_type = event_type - self.callback_url = callback_url - if integration is not None: - self.integration = integration - if created is not None: - self.created = created - - @property - def url(self): - """Gets the url of this WebhookSubscription. # noqa: E501 - - - :return: The url of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._url - - @url.setter - def url(self, url): - """Sets the url of this WebhookSubscription. - - - :param url: The url of this WebhookSubscription. # noqa: E501 - :type: str - """ - - self._url = url - - @property - def uuid(self): - """Gets the uuid of this WebhookSubscription. # noqa: E501 - - - :return: The uuid of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._uuid - - @uuid.setter - def uuid(self, uuid): - """Sets the uuid of this WebhookSubscription. - - - :param uuid: The uuid of this WebhookSubscription. # noqa: E501 - :type: str - """ - if uuid is not None and len(uuid) < 1: - raise ValueError("Invalid value for `uuid`, length must be greater than or equal to `1`") # noqa: E501 - - self._uuid = uuid - - @property - def name(self): - """Gets the name of this WebhookSubscription. # noqa: E501 - - Optional name to easily identify what webhook is used for # noqa: E501 - - :return: The name of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._name - - @name.setter - def name(self, name): - """Sets the name of this WebhookSubscription. - - Optional name to easily identify what webhook is used for # noqa: E501 - - :param name: The name of this WebhookSubscription. # noqa: E501 - :type: str - """ - if name is not None and len(name) > 255: - raise ValueError("Invalid value for `name`, length must be less than or equal to `255`") # noqa: E501 - - self._name = name - - @property - def event_type(self): - """Gets the event_type of this WebhookSubscription. # noqa: E501 - - - :return: The event_type of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._event_type - - @event_type.setter - def event_type(self, event_type): - """Sets the event_type of this WebhookSubscription. - - - :param event_type: The event_type of this WebhookSubscription. # noqa: E501 - :type: str - """ - if event_type is None: - raise ValueError("Invalid value for `event_type`, must not be `None`") # noqa: E501 - allowed_values = ["convert_error", "converted", "sending_error", "sent", "declined", "cancelled", "expired", "signed", "viewed", "downloaded", "signer_signed", "signer_email_bounced", "signer_viewed_email", "signer_viewed", "signer_forwarded", "signer_downloaded", "signrequest_received"] # noqa: E501 - if event_type not in allowed_values: - raise ValueError( - "Invalid value for `event_type` ({0}), must be one of {1}" # noqa: E501 - .format(event_type, allowed_values) - ) - - self._event_type = event_type - - @property - def callback_url(self): - """Gets the callback_url of this WebhookSubscription. # noqa: E501 - - - :return: The callback_url of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._callback_url - - @callback_url.setter - def callback_url(self, callback_url): - """Sets the callback_url of this WebhookSubscription. - - - :param callback_url: The callback_url of this WebhookSubscription. # noqa: E501 - :type: str - """ - if callback_url is None: - raise ValueError("Invalid value for `callback_url`, must not be `None`") # noqa: E501 - if callback_url is not None and len(callback_url) > 2100: - raise ValueError("Invalid value for `callback_url`, length must be less than or equal to `2100`") # noqa: E501 - if callback_url is not None and len(callback_url) < 1: - raise ValueError("Invalid value for `callback_url`, length must be greater than or equal to `1`") # noqa: E501 - - self._callback_url = callback_url - - @property - def integration(self): - """Gets the integration of this WebhookSubscription. # noqa: E501 - - - :return: The integration of this WebhookSubscription. # noqa: E501 - :rtype: str - """ - return self._integration - - @integration.setter - def integration(self, integration): - """Sets the integration of this WebhookSubscription. - - - :param integration: The integration of this WebhookSubscription. # noqa: E501 - :type: str - """ - allowed_values = ["mfiles", "salesforce", "formdesk", "zapier", "txhash"] # noqa: E501 - if integration not in allowed_values: - raise ValueError( - "Invalid value for `integration` ({0}), must be one of {1}" # noqa: E501 - .format(integration, allowed_values) - ) - - self._integration = integration - - @property - def created(self): - """Gets the created of this WebhookSubscription. # noqa: E501 - - - :return: The created of this WebhookSubscription. # noqa: E501 - :rtype: datetime - """ - return self._created - - @created.setter - def created(self, created): - """Sets the created of this WebhookSubscription. - - - :param created: The created of this WebhookSubscription. # noqa: E501 - :type: datetime - """ - - self._created = created - - def to_dict(self): - """Returns the model properties as a dict""" - result = {} - - for attr, _ in six.iteritems(self.swagger_types): - value = getattr(self, attr) - if isinstance(value, list): - result[attr] = list(map( - lambda x: x.to_dict() if hasattr(x, "to_dict") else x, - value - )) - elif hasattr(value, "to_dict"): - result[attr] = value.to_dict() - elif isinstance(value, dict): - result[attr] = dict(map( - lambda item: (item[0], item[1].to_dict()) - if hasattr(item[1], "to_dict") else item, - value.items() - )) - else: - result[attr] = value - - return result - - def to_str(self): - """Returns the string representation of the model""" - return pprint.pformat(self.to_dict()) - - def __repr__(self): - """For `print` and `pprint`""" - return self.to_str() - - def __eq__(self, other): - """Returns true if both objects are equal""" - if not isinstance(other, WebhookSubscription): - return False - - return self.__dict__ == other.__dict__ - - def __ne__(self, other): - """Returns true if both objects are not equal""" - return not self == other diff --git a/signrequest_python_client/rest.py b/signrequest_python_client/rest.py deleted file mode 100644 index 4603c91..0000000 --- a/signrequest_python_client/rest.py +++ /dev/null @@ -1,323 +0,0 @@ -# coding: utf-8 - -""" - SignRequest API - - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 - - OpenAPI spec version: v1 - Contact: tech-support@signrequest.com - Generated by: https://github.com/swagger-api/swagger-codegen.git -""" - - -from __future__ import absolute_import - -import io -import json -import logging -import re -import ssl - -import certifi -# python 2 and python 3 compatibility library -import six -from six.moves.urllib.parse import urlencode - -try: - import urllib3 -except ImportError: - raise ImportError('Swagger python client requires urllib3.') - - -logger = logging.getLogger(__name__) - - -class RESTResponse(io.IOBase): - - def __init__(self, resp): - self.urllib3_response = resp - self.status = resp.status - self.reason = resp.reason - self.data = resp.data - - def getheaders(self): - """Returns a dictionary of the response headers.""" - return self.urllib3_response.getheaders() - - def getheader(self, name, default=None): - """Returns a given response header.""" - return self.urllib3_response.getheader(name, default) - - -class RESTClientObject(object): - - def __init__(self, configuration, pools_size=4, maxsize=None): - # urllib3.PoolManager will pass all kw parameters to connectionpool - # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75 # noqa: E501 - # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680 # noqa: E501 - # maxsize is the number of requests to host that are allowed in parallel # noqa: E501 - # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html # noqa: E501 - - # cert_reqs - if configuration.verify_ssl: - cert_reqs = ssl.CERT_REQUIRED - else: - cert_reqs = ssl.CERT_NONE - - # ca_certs - if configuration.ssl_ca_cert: - ca_certs = configuration.ssl_ca_cert - else: - # if not set certificate file, use Mozilla's root certificates. - ca_certs = certifi.where() - - addition_pool_args = {} - if configuration.assert_hostname is not None: - addition_pool_args['assert_hostname'] = configuration.assert_hostname # noqa: E501 - - if maxsize is None: - if configuration.connection_pool_maxsize is not None: - maxsize = configuration.connection_pool_maxsize - else: - maxsize = 4 - - # https pool manager - if configuration.proxy: - self.pool_manager = urllib3.ProxyManager( - num_pools=pools_size, - maxsize=maxsize, - cert_reqs=cert_reqs, - ca_certs=ca_certs, - cert_file=configuration.cert_file, - key_file=configuration.key_file, - proxy_url=configuration.proxy, - **addition_pool_args - ) - else: - self.pool_manager = urllib3.PoolManager( - num_pools=pools_size, - maxsize=maxsize, - cert_reqs=cert_reqs, - ca_certs=ca_certs, - cert_file=configuration.cert_file, - key_file=configuration.key_file, - **addition_pool_args - ) - - def request(self, method, url, query_params=None, headers=None, - body=None, post_params=None, _preload_content=True, - _request_timeout=None): - """Perform requests. - - :param method: http request method - :param url: http request url - :param query_params: query parameters in the url - :param headers: http request headers - :param body: request json body, for `application/json` - :param post_params: request post parameters, - `application/x-www-form-urlencoded` - and `multipart/form-data` - :param _preload_content: if False, the urllib3.HTTPResponse object will - be returned without reading/decoding response - data. Default is True. - :param _request_timeout: timeout setting for this request. If one - number provided, it will be total request - timeout. It can also be a pair (tuple) of - (connection, read) timeouts. - """ - method = method.upper() - assert method in ['GET', 'HEAD', 'DELETE', 'POST', 'PUT', - 'PATCH', 'OPTIONS'] - - if post_params and body: - raise ValueError( - "body parameter cannot be used with post_params parameter." - ) - - post_params = post_params or {} - headers = headers or {} - - timeout = None - if _request_timeout: - if isinstance(_request_timeout, (int, ) if six.PY3 else (int, long)): # noqa: E501,F821 - timeout = urllib3.Timeout(total=_request_timeout) - elif (isinstance(_request_timeout, tuple) and - len(_request_timeout) == 2): - timeout = urllib3.Timeout( - connect=_request_timeout[0], read=_request_timeout[1]) - - if 'Content-Type' not in headers: - headers['Content-Type'] = 'application/json' - - try: - # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE` - if method in ['POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE']: - if query_params: - url += '?' + urlencode(query_params) - if re.search('json', headers['Content-Type'], re.IGNORECASE): - request_body = None - if body is not None: - request_body = json.dumps(body) - r = self.pool_manager.request( - method, url, - body=request_body, - preload_content=_preload_content, - timeout=timeout, - headers=headers) - elif headers['Content-Type'] == 'application/x-www-form-urlencoded': # noqa: E501 - r = self.pool_manager.request( - method, url, - fields=post_params, - encode_multipart=False, - preload_content=_preload_content, - timeout=timeout, - headers=headers) - elif headers['Content-Type'] == 'multipart/form-data': - # must del headers['Content-Type'], or the correct - # Content-Type which generated by urllib3 will be - # overwritten. - del headers['Content-Type'] - r = self.pool_manager.request( - method, url, - fields=post_params, - encode_multipart=True, - preload_content=_preload_content, - timeout=timeout, - headers=headers) - # Pass a `string` parameter directly in the body to support - # other content types than Json when `body` argument is - # provided in serialized form - elif isinstance(body, str): - request_body = body - r = self.pool_manager.request( - method, url, - body=request_body, - preload_content=_preload_content, - timeout=timeout, - headers=headers) - else: - # Cannot generate the request from given parameters - msg = """Cannot prepare a request message for provided - arguments. Please check that your arguments match - declared content type.""" - raise ApiException(status=0, reason=msg) - # For `GET`, `HEAD` - else: - r = self.pool_manager.request(method, url, - fields=query_params, - preload_content=_preload_content, - timeout=timeout, - headers=headers) - except urllib3.exceptions.SSLError as e: - msg = "{0}\n{1}".format(type(e).__name__, str(e)) - raise ApiException(status=0, reason=msg) - - if _preload_content: - r = RESTResponse(r) - - # In the python 3, the response.data is bytes. - # we need to decode it to string. - if six.PY3: - r.data = r.data.decode('utf8') - - # log response body - logger.debug("response body: %s", r.data) - - if not 200 <= r.status <= 299: - raise ApiException(http_resp=r) - - return r - - def GET(self, url, headers=None, query_params=None, _preload_content=True, - _request_timeout=None): - return self.request("GET", url, - headers=headers, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - query_params=query_params) - - def HEAD(self, url, headers=None, query_params=None, _preload_content=True, - _request_timeout=None): - return self.request("HEAD", url, - headers=headers, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - query_params=query_params) - - def OPTIONS(self, url, headers=None, query_params=None, post_params=None, - body=None, _preload_content=True, _request_timeout=None): - return self.request("OPTIONS", url, - headers=headers, - query_params=query_params, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - - def DELETE(self, url, headers=None, query_params=None, body=None, - _preload_content=True, _request_timeout=None): - return self.request("DELETE", url, - headers=headers, - query_params=query_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - - def POST(self, url, headers=None, query_params=None, post_params=None, - body=None, _preload_content=True, _request_timeout=None): - return self.request("POST", url, - headers=headers, - query_params=query_params, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - - def PUT(self, url, headers=None, query_params=None, post_params=None, - body=None, _preload_content=True, _request_timeout=None): - return self.request("PUT", url, - headers=headers, - query_params=query_params, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - - def PATCH(self, url, headers=None, query_params=None, post_params=None, - body=None, _preload_content=True, _request_timeout=None): - return self.request("PATCH", url, - headers=headers, - query_params=query_params, - post_params=post_params, - _preload_content=_preload_content, - _request_timeout=_request_timeout, - body=body) - - -class ApiException(Exception): - - def __init__(self, status=None, reason=None, http_resp=None): - if http_resp: - self.status = http_resp.status - self.reason = http_resp.reason - self.body = http_resp.data - self.headers = http_resp.getheaders() - else: - self.status = status - self.reason = reason - self.body = None - self.headers = None - - def __str__(self): - """Custom error messages for exception""" - error_message = "({0})\n"\ - "Reason: {1}\n".format(self.status, self.reason) - if self.headers: - error_message += "HTTP response headers: {0}\n".format( - self.headers) - - if self.body: - error_message += "HTTP response body: {0}\n".format(self.body) - - return error_message diff --git a/test/test_api_tokens_api.py b/test/test_api_tokens_api.py index 56e2f84..9d25929 100644 --- a/test/test_api_tokens_api.py +++ b/test/test_api_tokens_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_auth_token.py b/test/test_auth_token.py index 76c7395..05858d3 100644 --- a/test/test_auth_token.py +++ b/test/test_auth_token.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_document.py b/test/test_document.py index 61c6326..1bf8a4b 100644 --- a/test/test_document.py +++ b/test/test_document.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_document_attachment.py b/test/test_document_attachment.py index 83d8b5c..a0e2cbb 100644 --- a/test/test_document_attachment.py +++ b/test/test_document_attachment.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_document_attachments_api.py b/test/test_document_attachments_api.py index 401e06c..c1bf201 100644 --- a/test/test_document_attachments_api.py +++ b/test/test_document_attachments_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_document_search.py b/test/test_document_search.py index 4142575..9551920 100644 --- a/test/test_document_search.py +++ b/test/test_document_search.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_document_signer_template_conf.py b/test/test_document_signer_template_conf.py index f0378bb..aab7729 100644 --- a/test/test_document_signer_template_conf.py +++ b/test/test_document_signer_template_conf.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_documents_api.py b/test/test_documents_api.py index 4b95501..cd9ee1c 100644 --- a/test/test_documents_api.py +++ b/test/test_documents_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_documents_search_api.py b/test/test_documents_search_api.py index b283102..870f720 100644 --- a/test/test_documents_search_api.py +++ b/test/test_documents_search_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_event.py b/test/test_event.py index 9d16729..9ac0a21 100644 --- a/test/test_event.py +++ b/test/test_event.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_events_api.py b/test/test_events_api.py index 7147bf5..7ab731a 100644 --- a/test/test_events_api.py +++ b/test/test_events_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_file_from_sf.py b/test/test_file_from_sf.py index 879f429..e852d57 100644 --- a/test/test_file_from_sf.py +++ b/test/test_file_from_sf.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_document_signer_integration_data.py b/test/test_inline_document_signer_integration_data.py index 33051a4..3e8ae29 100644 --- a/test/test_inline_document_signer_integration_data.py +++ b/test/test_inline_document_signer_integration_data.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_integration_data.py b/test/test_inline_integration_data.py index 3ad27ec..1e3e65f 100644 --- a/test/test_inline_integration_data.py +++ b/test/test_inline_integration_data.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_prefill_tags.py b/test/test_inline_prefill_tags.py index b21d4ea..5ed1bf8 100644 --- a/test/test_inline_prefill_tags.py +++ b/test/test_inline_prefill_tags.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200.py b/test/test_inline_response_200.py index e2c074b..3a82aec 100644 --- a/test/test_inline_response_200.py +++ b/test/test_inline_response_200.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_1.py b/test/test_inline_response_200_1.py index f7a878d..bfa97ec 100644 --- a/test/test_inline_response_200_1.py +++ b/test/test_inline_response_200_1.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_2.py b/test/test_inline_response_200_2.py index 124fc5c..4bcbde5 100644 --- a/test/test_inline_response_200_2.py +++ b/test/test_inline_response_200_2.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_3.py b/test/test_inline_response_200_3.py index 75a27fc..042c842 100644 --- a/test/test_inline_response_200_3.py +++ b/test/test_inline_response_200_3.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_4.py b/test/test_inline_response_200_4.py index 1722b08..54679b5 100644 --- a/test/test_inline_response_200_4.py +++ b/test/test_inline_response_200_4.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_5.py b/test/test_inline_response_200_5.py index 5e28ab1..bcb158e 100644 --- a/test/test_inline_response_200_5.py +++ b/test/test_inline_response_200_5.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_6.py b/test/test_inline_response_200_6.py index 887f01e..102a470 100644 --- a/test/test_inline_response_200_6.py +++ b/test/test_inline_response_200_6.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_7.py b/test/test_inline_response_200_7.py index bbe1cb6..3f1185f 100644 --- a/test/test_inline_response_200_7.py +++ b/test/test_inline_response_200_7.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_8.py b/test/test_inline_response_200_8.py index 0424a2e..58c0378 100644 --- a/test/test_inline_response_200_8.py +++ b/test/test_inline_response_200_8.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_200_9.py b/test/test_inline_response_200_9.py index cd08a76..6d90b20 100644 --- a/test/test_inline_response_200_9.py +++ b/test/test_inline_response_200_9.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_201.py b/test/test_inline_response_201.py index 9642b19..6c1e9b0 100644 --- a/test/test_inline_response_201.py +++ b/test/test_inline_response_201.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_response_201_1.py b/test/test_inline_response_201_1.py index 9ff84e8..6d57cc1 100644 --- a/test/test_inline_response_201_1.py +++ b/test/test_inline_response_201_1.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_sign_request.py b/test/test_inline_sign_request.py index 722e0b7..99cb52a 100644 --- a/test/test_inline_sign_request.py +++ b/test/test_inline_sign_request.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_team.py b/test/test_inline_team.py index b38f6ef..c0202f0 100644 --- a/test/test_inline_team.py +++ b/test/test_inline_team.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_inline_team_member.py b/test/test_inline_team_member.py index 4bd90f7..569941f 100644 --- a/test/test_inline_team_member.py +++ b/test/test_inline_team_member.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_invite_member.py b/test/test_invite_member.py index e0146e7..f40b171 100644 --- a/test/test_invite_member.py +++ b/test/test_invite_member.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_placeholder.py b/test/test_placeholder.py index 0d527d5..7109b7c 100644 --- a/test/test_placeholder.py +++ b/test/test_placeholder.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_required_attachment.py b/test/test_required_attachment.py index 52f42a0..2bccd55 100644 --- a/test/test_required_attachment.py +++ b/test/test_required_attachment.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_sign_request.py b/test/test_sign_request.py index a4ad471..f4629c8 100644 --- a/test/test_sign_request.py +++ b/test/test_sign_request.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"tech-support@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. The numbers in the tags are used to make distinctions between the signers and group multiple tags (input fields) to one specific signer. The template tags are assigned to the order at which the email addresses are added to the contact field and are not the same as the order of signing. This means that for example `s|1` can be the first or last signer depending on what you specified in the order of signing (if used of course). As the sender is always the first email address added, this means the sender is always `s|0`. If the sender does not need to add a signature or other data input, then `s|0` will be assigned to the next in line. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ```html https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"tech-support@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` ## Tags Example Signer 0: this is the first person that needs to sign (including you). ![Signer 0](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-0.bf35c985.png) Signer 1: this is the second person that needs to sign (including you). ![Signer 1](https://signrequest.com/assets/images/blogs/template-tags-electronic-signature-1.335ad0c8.png) The result in SignRequest: ![Result in SignRequest](https://signrequest.com/assets/images/blogs/tags-example.2bb33d7f.png) ## Example Documents You can quickly test this feature with our example documents: 1. [Basic example document](https://docs.google.com/document/d/1oI2R1SxfMNZXiz3jCQvorpoklF9xq_dCJnOpkI-zo80/edit?usp=sharing) 2. [Advanced example document](https://docs.google.com/document/d/1-gzqym9clQ1a193JGocXUeIX92cqPINBHOBeGxbDASw/edit) These are shared Google Docs documents with example tags. If you have our Google Docs Add-on you can directly send a SignRequest! If you don't have our Google Docs Add-on for electronic signatures, go to \"Add-ons\" in the Google Docs menu bar and install the Add-on for free. Then, go back to \"Add-ons\" and click \"SignRequest\". ## Walkthrough Video We also have a walkthrough video on YouTube about using templates with tags in a base document: [![Templates with tags in a base document](http://img.youtube.com/vi/y5U5WqTqZBQ/0.jpg)](http://www.youtube.com/watch?v=y5U5WqTqZBQ) # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=tech-support@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '', // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"tech-support@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at tech-support@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_sign_request_quick_create.py b/test/test_sign_request_quick_create.py index fc7bdd7..27f6171 100644 --- a/test/test_sign_request_quick_create.py +++ b/test/test_sign_request_quick_create.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signer.py b/test/test_signer.py index 97d0802..28d66bc 100644 --- a/test/test_signer.py +++ b/test/test_signer.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signer_attachment.py b/test/test_signer_attachment.py index e6fa223..70592d7 100644 --- a/test/test_signer_attachment.py +++ b/test/test_signer_attachment.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signer_inputs.py b/test/test_signer_inputs.py index d3b34aa..98ee7d3 100644 --- a/test/test_signer_inputs.py +++ b/test/test_signer_inputs.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signing_log.py b/test/test_signing_log.py index 1244ecb..c1ab60d 100644 --- a/test/test_signing_log.py +++ b/test/test_signing_log.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signrequest_quick_create_api.py b/test/test_signrequest_quick_create_api.py index 04083bc..1833fb2 100644 --- a/test/test_signrequest_quick_create_api.py +++ b/test/test_signrequest_quick_create_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_signrequests_api.py b/test/test_signrequests_api.py index 43e7e5b..98428be 100644 --- a/test/test_signrequests_api.py +++ b/test/test_signrequests_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_team.py b/test/test_team.py index b6432b1..8c0a1e7 100644 --- a/test/test_team.py +++ b/test/test_team.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_team_member.py b/test/test_team_member.py index e809a30..b124f94 100644 --- a/test/test_team_member.py +++ b/test/test_team_member.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_team_members_api.py b/test/test_team_members_api.py index 527d1a2..ea82ef9 100644 --- a/test/test_team_members_api.py +++ b/test/test_team_members_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_teams_api.py b/test/test_teams_api.py index 52bf025..dfbf9f0 100644 --- a/test/test_teams_api.py +++ b/test/test_teams_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_template.py b/test/test_template.py index b69cd6c..243bb7f 100644 --- a/test/test_template.py +++ b/test/test_template.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_templates_api.py b/test/test_templates_api.py index 30b448d..ca7a2f1 100644 --- a/test/test_templates_api.py +++ b/test/test_templates_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_user.py b/test/test_user.py index d5e49ae..708ddeb 100644 --- a/test/test_user.py +++ b/test/test_user.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_webhook_subscription.py b/test/test_webhook_subscription.py index 0405999..89556f9 100644 --- a/test/test_webhook_subscription.py +++ b/test/test_webhook_subscription.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com diff --git a/test/test_webhooks_api.py b/test/test_webhooks_api.py index 9a70d1c..aaed470 100644 --- a/test/test_webhooks_api.py +++ b/test/test_webhooks_api.py @@ -3,7 +3,7 @@ """ SignRequest API - API for SignRequest.com # Getting Started The SignRequest REST API enables you to send out signature requests. Using the API you will always have all the functionality as when using the frontend plus more. When you're logged in and you have a Team enabled, you can also use the endpoints in your browser by visiting them. It is also possible to receive events from SignRequest when, for example, a document has been signed. This way you can keep your application in sync with SignRequest without polling document endpoints. For this a callback url needs to be provided in the [team API settings page](/#/teams). ## API Token In order to use the API you first need to obtain an API token. You can create an API token in the [team API settings page](/#/teams). It is also possible to get or create a token using the [api-tokens endpoint](#operation/api-tokens_create) with your login credentials. Use tokens with a `Authorization: Token YOUR_TOKEN_HERE` header in your requests when making requests to the SignRequest API. cURL example: ```bash curl -H 'Authorization: Token YOUR_TOKEN_HERE' -H 'Content-Type:application/json' ``` ## Creating a Document In order to send out a SignRequest we first need to create a document. There are three ways to create a document using the [documents endpoint](#operation/documents_create). One by sending a POST request that includes a `file`, two by providing `file_from_url` in which case SignRequest will download the document from that location, and three by providing base64 encoded document content in `file_from_content` together with the filename for this content in `file_from_content_name`. This can be useful if you have trouble POSTing the file together with other (nested, in the case of the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create)) configuration data. Please be sure to add the correct extension to the filename (e.g. my_pdf_file.pdf) in order for SignRequest to be able to determine the content type of the content. Note that when using `file_from_url`, this url needs to be available for SignRequest to download. The download location may also be a Google Drive shareable link for documents (`application/vnd.google-apps.document`) and files (`application/vnd.google-apps.file`) uploaded to Google Drive. If the download location returns a content type of `text/plain` or `text/html`, SignRequest will do its best to make a PDF out of it. This can be used if you want to dynamically create PDF documents from web pages without making a PDF yourself. `external_id` is optional and can be used in order to have a reference to the document in your systems. The `name` field is also optional and can be customized, defaults to the filename (including extension). ## Sending a SignRequest Once you have successfully created a document, you can use the [signrequests endpoint](#operation/signrequests_create) to send a SignRequest using the `url` returned from the [documents endpoint](#operation/documents_create). The minimal data needed to send out a SignRequest is the following: ```json { \"document\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"from_email\": \"you@yourcompany.com\", \"message\": \"Please sign this document.\\n\\nThanks!\", \"signers\": [ { \"email\": \"api@signrequest.com\" } ] } ``` Note that we always also create a signer for the `from_email` sending the SignRequest, however for this signer the `needs_to_sign` flag is set to `false` meaning that this signer will **not** get a SignRequest. ## Quick Create a SignRequest In some cases it might be desirable to create a document and send the SignRequest in one API call. This can be done using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). This endpoint takes all of the fields of the [documents](#operation/documents_create) and [signrequests](#operation/signrequests_create) endpoints together, creates the document, and sends the SignRequest. ## Browsable API In addition to our API docs, you can also explore our API endpoints using our [browsable API](/api/v1/). There you'll be able to browse our various endpoints and even perform requests against our live API. # Working with a SignRequest ## Add attachments to a SignRequest Attachments can be added to a SignRequest using the [document-attachments endpoint](#operation/document-attachments_create). Signers will be able to download and read them before signing, but these will not be signed themselves. Document attachments can only be added when the SignRequest is not created yet. ## Customizing the SignRequest email If the Team has a custom color and logo these will be used in the SignRequest email. The `subject` and `message` fields can also be used to customize the email even further. The `message` may contain the following html tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. When the `from_email_name` field is provided, this name will be used in the `From` email header as such `{from_email_name} `. By default `Sender Name (sender@email.com) | SignRequest` is used as the `from_email_name`. Note that it's currently not possible to change the email address used to send a SignRequest. ## Resend the SignRequest email(s) The [resend_signrequest_email](#operation/signrequests_resend_signrequest_email) endpoint can be used to resend the SignRequest email as a reminder to all signers who didn't sign yet but did receive the email before. ## Cancel a SignRequest A SignRequest that has not been fully signed or declined yet can be cancelled using the [cancel_signrequest endpoint](#operation/signrequests_cancel_signrequest). By doing so all signers that have not signed yet will not be able to open and sign the document anymore. ## Download a signed document When a SignRequest has been signed the `pdf` field on the document resource will be filled with a link to download the signed PDF. The signing log PDF can be downloaded from the `pdf` field contained within the `signing_log` object field on the document resource. The recommended way to download the files and store them in your own systems is to setup the [Events callback](#section/Events/Events-callback) functionality and have your application download the files on the `signed` (Document signed) event. Please note that the download links expire and are regenerated on every API call / events callback so download the files right away when needed. ## Deleting documents To delete a document for the owner of the document, send a DELETE request to the [document resource url](#operation/documents_delete). Note that at this point this only makes the document unavailable for the sender. For all signers that do not have a registered SignRequest account, a grace period is started to give them a chance to download the signed document. After this grace period the document will be deleted for these signers automatically. When all signers have requested a delete (manually, automatically, or via the API) or do not have a registered SignRequest account and the grace period has lapsed, the document will be fully deleted. ### Automatic document deletion To automatically delete a document the `auto_delete_days` field on a document can be set to a number of days after which a finished document (signed/cancelled/declined) will be automatically deleted. The behavior is the same as doing a DELETE on the document resource url X number of days after the document is finished. When the document is scheduled to be deleted the `auto_delete_after` will hold the date after which it will be deleted. Note that we can make exceptions (to delete documents right away and entirely) for integration partners when they make the document available in other systems and users do not use SignRequest directly. Please [contact us](https://signrequest.com/en/contact/) to request an app screening if this functionality is required. ## Chaining multiple documents When sending a SignRequest, it's possible to reference a document in the `after_document` field on a `signer`. This should reference a document that the signer should be redirected to after signing. Since the signer is redirected to this document immediately after signing the other document, they do NOT get a SignRequest email. Note that resending the SignRequest email will trigger the SignRequest email even though they didn't receive one before. When `after_document` references a document where the signer in question already has signed or declined they will still receive a SignRequest email as we cannot redirect them anymore. It's only possible to reference documents that are not fully signed (or declined) yet. A `redirect_url` field is also available on a `signer` and on the `signrequest` (the default when not specified on the individual signers explicitly). When specified SignRequest will redirect to this url when a document is signed. Note that this only works when there are no chained documents for this signer anymore. Chaining also works on the [signrequest-quick-create endpoint](#operation/signrequest-quick-create_create). When creating a SignRequest on that endpoint, you get a reference to the created document in the `document` field back which can be used in the next call to `signrequest-quick-create` when creating a chain with `after_document`. ## Signer language If known the language of the signer can be set in the `language` field. This will determine the language of the SignRequest email. The SignRequest browser interface language is by default set to the location, browser, or user account settings when available. To force the language of the interface when a signer lands on the signing page the field `force_language` on the signer can be set to `true`. Note that if the language of the signer is not known it's best to not force the language. Available languages: `en` English `en-gb` English (GB) `nl` Dutch `fr` French `de` German `he` Hebrew `da` Danish `fi` Finnish `hu` Hungarian `it` Italian `no` Norwegian `pl` Polish `pt` Portuguese `es` Spanish `sv` Swedish `ru` Russian ## Text message and bank account verification For a higher degree of authentication of your signers it is possible to enable text message phone number verification and bank account verification. These verifications can be enabled by providing the phone number to `verify_phone_number` (international format including the plus-sign) and/or the bank account to `verify_bank_account` on a signer. Currently it is only possible to verify bank accounts using [iDEAL](https://www.ideal.nl/en/). When enabled, signers can only sign (finalize) a document when they have verified their phone number by a code supplied to them by a text message and/or make a payment of 1 cent. The verifications are logged and visible in the SignRequest signing log after completion. Please note that we cannot force signers to make a payment using a specific bank account. Therefore the content of the field may also specify what type of account to use instead of a specific bank account number, e.g.: \"the bank account you want to use for paying the rent.\" For this service additional fees apply. Please [contact us](https://signrequest.com/en/contact/) for a quote. ## Disable signing tools/features It is possible to disable certain tools/features signers have when signing a document. The following flags can be set to `true` on the signrequest model to disable these features. - `disable_text`: disable adding of text - `disable_date`: disable adding of dates - `disable_attachments`: disable uploading/adding of attachments - `disable_text_signatures`: disable usage of signatures generated by typing (text) - `disable_upload_signatures`: disable usage of uploaded signatures (images) Please note that we strongly **discourage you to disable features** as these are carefully chosen for optimal usability of the SignRequest product. ## Required attachments To require signers to upload attachments (like a passport for example) the `required_attachments` field can be used. The field takes an array of objects with one parameter `name`, for example: `required_attachments: [{\"name\": \"Passport\"}]` ## Templates In the frontend application it is possible to create templates. These templates, for Teams and Personal accounts, can be found in the [templates resource](#tag/templates). In order to send a SignRequest using a template, reference the resource url of the template in the `template` field. This works in both the [documents](#tag/documents) and the [signrequest-quick-create](#tag/signrequest-quick-create) resources. ## Automatic reminders To enable automatic reminders set the `send_reminders` boolean to `true` on the [SignRequest resource](#tag/signrequests). When enabled SignRequest will automatically remind signers to sign a document. # Preparing a document Using the SignRequest frontend web application you have the option to \"prepare\" a document. This helps the receiver as they can only sign the document at the designated place. Using the API you can also **prepare a document by using tags** to specify where a signer needs to add a date, text, checkbox, and/or a signature. Tags need to start with `[[` and end with `]]`. The tag data is separated by a pipe `|`. The first letter of the tag represents the tag type and must be one of the following: - `t` for text - `d` for date - `s` for signature - `c` for checkbox The second piece of data is an integer representing the index of the signer for which this placeholder is intended. For this reason the order at which you add signers to the array matters. If the owner (sender) needs to sign this will always be index `0`. Mismatches in the amount of declared placeholders and available signers will be silently ignored. The extra placeholders will not show up if more than the amount of signers **OR** signers just get an unprepared document to sign when there were no placeholders declared for them. Examples: ``` [[s|0 ]] // A signature for the first signer OR the owner/sender when they need to sign. [[c|0 ]] // A checkbox placeholder for the first signer [[d|1 ]] // A date input placeholder for the second signer [[t|2 ]] // A text input placeholder for the third signer ``` The height / width (font size) and the position of the tag in your document matters. Also as you do not want the **placeholder tag to show up in the document** to avoid this you need to make the font color match the background. Sign this demo document for an example (the color is left gray to see the tags): ``` https://signrequest.com/#/?api=v1&who=m&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestTagsExample.pdf ``` Note that the font chosen can make a difference in the bounding box margins and position. For most fonts the top margin will be bigger as desired. For this reason make sure to **leave enough space or double the line height** in order for the placeholder to not overlap the line above. ## Tag modifiers There are multiple tag modifiers available to further customize the tags. The following key / value pairs can be used after the signer index. - `r` to make a placeholder required to be filled: `1` / `true` for required `0` / `false` for not required - `m` to make a text placeholder multiline: `1` / `true` for multiline `0` / `false` for single line (default) - `n` to set a label/name on a text placeholder: 'a string' - `p` to prefill text/dates on a text/date placeholder: 'a string', for a date placeholder this can also be set to `0` / `false` to not prefill the current date. - `id` to assign an `external_id` to the placeholder: \"your_id\" (also see [Retrieving signer input](#section/Preparing-a-document/Retrieving-signer-input) and [Prefill tags](#section/Preparing-a-document/Prefill-tags-templates)) Examples: ``` [[c|0|r:1 ]] // A checkbox that cannot be skipped (needs to be checked or not) [[c|0|r:0 ]] // A checkbox that can be skipped [[c|0|p:1 ]] // A checkbox that is by default checked (can be changed) [[d|0|n:Birth date|p:0 ]] // A date that is not prefilled with the date of signing and has the label 'Birth date' [[t|0|n:City|p:New York|id:customer_city ]] // A text input placeholder with the label 'City', prefilled with the text 'New York' and an external_id of 'customer_city' that will be available later in the 'inputs' field (see: 'Retrieving signer input') and can be used to prefill the tag using prefill_tags on the document resource (see: 'Prefill tags'). ``` Note that placeholder names / prefilled data can get quite long. If this impacts the placeholder width/height you can choose to make the font between the opening `[[` and closing `]]` tags (really) small. The tag configuration does not need to be human readable as the text is extracted from the PDF format directly. ## Prefill tags / templates Instead of generating a new document and use the `p` tag modifier to prefill signer input data it is also possible to use `prefill_tags`. For this to work all tags need to have an `id` as this is needed to reference the tag. Example: ``` [[c|0|id:checkbox_1 ]] // Should be checked [[c|0|id:checkbox_2 ]] // Should not be checked [[d|0|n:Birth date|id:birth_date ]] // Should be prefilled with the birth date of the signer [[t|0|n:City|id:customer_city ]] // Should be prefilled with 'New York' ``` Now when a document contains the tags above you can prefill them using the `prefill_tags` field on document by referencing the 'id'. ```json \"prefill_tags\": [ {\"external_id\":\"checkbox_1\", \"checkbox_value\":\"true\"}, {\"external_id\":\"checkbox_2\", \"checkbox_value\":\"false\"}, {\"external_id\":\"birth_date\", \"date_value\":\"1984-12-31\"}, // must be in ISO format ([YYYY]-[MM]-[DD]) {\"external_id\":\"customer_city\", \"text\":\"New York\"} ] ``` If you are using templates created from within the SignRequest app you can also set the `external_id` of a template tag in the advanced section when editing a tag. Note that it's also possible to add these tags when using the SignRequest-js client and the [Frontend API](#section/Frontend-API). ## Prepare using the web interface It is also possible to have the sender of a SignRequest prepare the document before sending the request out. To use this functionality, set the `is_being_prepared` flag on the SignRequest resource to `true`. When doing so the SignRequest will not be sent out to the recipient(s) and the `prepare_url` field will be set to a url where your application can redirect the sender to. Please note that if the sender does not have a SignRequest account they will be asked to verify their email after preparing the document. If you're an integration partner please [contact us](https://signrequest.com/en/contact/) for more possibilities when integrating this functionality. Example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"is_being_prepared\": \"true\", \"signers\": [{\"email\": \"you@yourcompany.com\"}, {\"email\": \"info@signrequest.com\"}] } ``` Note that it's perfectly fine to also include tags in the document. The sender will be able to change / remove them. ## Retrieving signer input All text, date, and boolean inputs of signers after a signer signs are available in the `inputs` field of a signer as text. This can be helpful if you need to update your systems based on data signers add to a document. ```json \"inputs\": [ { \"type\": \"d\", // 's' (signature input), 't' (text input), 'd' (date input) or 'c' (checkbox input) \"page_index\": 0, // index of the page this input resides on \"text\": \"09-25-18\", // text as seen on the document (only for date and text inputs) \"checkbox_value\": null, // true or false (only for checkbox inputs) \"date_value\": \"2018-09-25\", // the date in ISO format ([YYYY]-[MM]-[DD]) \"external_id\": null // optionally the external id assigned to a tag (helpful if you need to identify a specific input, also see 'Tag modifiers') } ] ``` # Events ## Events callback In order to receive the `events` as a callback to your application a **callback url** needs to be set in the [team API settings](/#/teams) page. When set, SignRequest will POST events as `application/json` to this endpoint. Your endpoint should return a 200 OK response. SignRequest will retry to deliver events (max 10 times) in case of a timeout or a 500 response from your server. It is also possible to change the **callback url on a per document basis**. To use this functionality you can set the callback url using the `events_callback_url` field when [creating a document](#operation/documents_create) or when using the [signrequest-quick-create endpoint](#tag/signrequest-quick-create). Please be aware that we might add more event types in the future so code defensively for that. For an example of how an event receiver can be written checkout this [repository](https://github.com/SignRequest/signrequest-event-receiver). The following event types are available: - `convert_error`: Document convert error - `converted`: Document converted - `sending_error`: Document sending error - `sent`: Document sent - `declined`: Document declined - `cancelled`: Document cancelled - `signed`: Document signed - `signer_signed`: Signer signed - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_forwarded`: Signer forwarded document - `signer_downloaded`: Signer downloaded - `signrequest_received`: SignRequest received Status codes: - `ok`: ok - `error`: error The event status will be `error` for the following events: `convert_error`, `sending_error`, and `signer_email_bounced`. The document status field can have the following codes: - `co`: converting - `ne`: new - `se`: sent - `vi`: viewed - `si`: signed - `do`: downloaded - `sd`: signed and downloaded - `ca`: cancelled - `de`: declined - `ec`: error converting - `es`: error sending Example callback request: ```json { \"document\": { \"api_used\": true, \"attachments\": [], \"external_id\": \"your_id_of_this_document\", \"file\": \"signrequest download url of the uploaded file\", \"file_from_url\": \"url where signrequest downloaded the document, if this functionality was used\", \"name\": \"document.pdf\", \"pdf\": null, \"prefill_tags\": [], \"security_hash\": null, \"signing_log\": null, \"signrequest\": null, \"status\": \"co\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"template\": null, \"url\": \"https://signrequest.com/api/v1/documents/f2bac751-4fa1-43f1-91de-a1b8905c239a/\", \"user\": null, \"uuid\": \"f2bac751-4fa1-43f1-91de-a1b8905c239a\" }, \"event_hash\": \"89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7\", \"event_time\": \"1537889008\", \"event_type\": \"converted\", \"signer\": null, \"status\": \"ok\", \"team\": { \"name\": \"the_name_of_your_team\", \"subdomain\": \"the_subdomain_of_your_team\" }, \"timestamp\": \"2018-09-25T15:23:28.836457Z\", \"token_name\": \"Token\", \"uuid\": \"ffffd4dd-89c7-4133-ba2d-960f65c8d395\" } ``` If the event is **signer related** the `signer` field will contain all the signer data. All event data can also be fetched using the REST API [Events resource](#tag/events). Be sure to check that out if you're developing your endpoint and see how the data looks. You can check the authenticity (that the event really came from SignRequest) by generating and comparing the `event_hash` that comes with the event. The `event_hash` is generated with the HMAC algorithm using your API Token as a key in SHA256 digest mode. OpenSSL shell example: ```bash echo -n \"${event_time}${event_type}\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" ``` which expands to: ```bash echo -n \"1537889008converted\" | openssl dgst -sha256 -hmac \"YOUR_TOKEN_HERE\" 89365cda10349ced9c3fd9c457372b37ad2e723c5b9f11a4d0b2c16724d8a2e7 ``` If you have multiple API tokens created you can identify the used token by the `token_name` (if you provided one). Always use **SSL enabled endpoints**! Developing your callback endpoint locally? Checkout [UltraHook](http://www.ultrahook.com/) to receive webhooks on localhost, nifty! ## Event webhooks To receive only specific event callbacks, webhook subscriptions can be created for Teams and for Personal accounts. The resource takes an `event_type`, `callback_url` and optionally a `name` to easily identify what webhook is used for. The `integration` field can also be set when this hook is specific to one of the SignRequest supported integrations. Check out the [webhooks resource](#tag/webhooks) for all possible event types to subscribe to. When the webhooks are used on personal accounts these webhooks also receive the `signrequest_received` event which can be used to notify users that they have received a new SignRequest. However, creating webhook subscriptions for personal accounts requires a SignRequest session (logged in user) or Basic auth using a username and password. ## Disable all SignRequest email events It is possible to disable all SignRequest status emails as well as the email that contains the signed documents. When using this functionality the following events will not generate a SignRequest email: - `sent`: Document sent - `signer_email_bounced`: Signer email bounced - `signer_viewed_email`: Signer viewed email - `signer_viewed`: Signer viewed document - `signer_signed`: Signer signed - `signed`: Document signed - `declined`: Document declined - `cancelled`: Document cancelled To enable this feature set the `disable_emails` flag on the [SignRequest resource](#tag/signrequests) to true. Note that the event emails will only be disabled if there is `callback_url` available for the document as your application is expected to notify users instead of SignRequest. The initial SignRequest email (that contains the link to sign) can only be disabled by using the [Embed url](#section/Additional-signing-methods/Embed-url) functionality. # Frontend API Another option to help your users sending SignRequests is using the \"frontend\" api. This involves no token and is merely used to \"prefill\" the SignRequest box found at the homepage for your users. The only requirement is that the document to send out is publicly available in order for SignRequest to download the file. Shareable links of Google Drive documents are also supported here. GET params for prefilling the box: ``` api=v1 // the version of the API to use who=mo // mo='me & others', m='only me', o='only others' signers=first_email@example.com,second_email@example.com // emails of 'signers' comma separated from_email=you@yourcompany.com // email of the person sending the SignRequest doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf // the url where SignRequest can download the document (quoted) ``` Example resulting url: ``` https://signrequest.com/#/?api=v1&who=mo&signers=api@signrequest.com&from_email=you@yourcompany.com&doc_url=https%3A%2F%2Fsignrequest.com%2Fstatic%2Fdemo%2FSignRequestDemoDocument.pdf ``` Note that you can also use prefill tags here by adding the parameter prefill_tags. The value should be Base64 encoded JSON, JavaScript example: ```javascript btoa(JSON.stringify([{external_id: 'customer_city', text: 'New York'}])); // the output can be used with the parameter: // prefill_tags=W3siZXh0ZXJuYWxfaWQiOiJjdXN0b21lcl9jaXR5IiwidGV4dCI6Ik5ldyBZb3JrIn1d ``` ## SignRequest-js client (beta) Although we consider the library \"beta\" you can count on a stable API (semver). However, if you plan to use this please [contact us](https://signrequest.com/en/contact/) so we know your use case and can help you out where needed. We will open up the repository to the public when out of beta. To use the SignRequest javascript library include the following in your page (npm and bower are coming when out of beta): ```html ``` Or for async loading use: ```html ``` The library uses [UMD](https://github.com/umdjs/umd) (Universal Module Definition). To use a specific version (current is **1.0.5**) use for example: **cdn.signrequest.com/signrequest-js/v1/1.0.5/signrequest-js.min.js**. ### Usage ```javascript // same as the frontend API GET parameters, these are all optional var conf = { subdomain: '' // if you are using this for a specific team set the subdomain here api: 'v1', who: 'mo', signers: 'first_email@example.com,second_email@example.com', from_email: 'you@yourcompany.com', close: true, // close the popup when done? default: true // or use next: next: '', // redirect to this url when done signing themselves, frontend_id: '' // optional shared secret set on document to grant access to users even if they don't have access to team } // these are also optional, the popup will be centered in the window opening the popup var popup_conf = { width: 460, // width of the popup in pixels, default 460 height: 600, // height of the popup in pixels, default the height of the window opening the popup } // to open a specific document first create a document using the REST API with your backend // be sure to also set the correct 'subdomain' in the configuration when you create a document for a specific team var doc_uuid = 'the-uuid-of-the-document'; SignRequest.browser.openPopupForDocUuid(doc_uuid, conf, popup_conf); // to create a document from a url var doc_url = 'https://signrequest.com/static/demo/SignRequestDemoDocument.pdf' SignRequest.browser.openPopupForDocUrl(doc_url, conf, popup_conf); // to create a document from a template uuid var template_uuid = 'the-uuid-of-the-template' SignRequest.browser.openPopupForTemplateUuid(template_uuid, conf, popup_conf); // to open a popup using custom params var popup = SignRequest.browser.openPopup(conf, popup_conf); // if your document contains template tags / placeholders that have an 'external_id' // it is possible to 'prefill' these for a particular SignRequest by updating your conf object with for example: conf.prefill_tags = [{external_id: 'customer_city', text: 'New York'}]; // Now all template tags with this external_id will be prefilled with 'New York' // all popup openers return an instance of the popup to which event callbacks can be registered (they can be chained) // the possible events are: 'opened', 'sent', 'signed', 'declined', 'finished', 'closed', 'any' // note that 'sent', 'finished' and 'closed' can be called fast after each other when the popup autocloses (close: true) // also when sending a SignRequest and the sender also need to sign you can receive the 'signed' or 'declined' event // after the 'sent' event (SignRequest created). // When the sender is done (sending and possibly siging) the 'finished' event is fired. popup = popup.on('closed', function (event_type, payload, event) { // this would fire when the popup closes, you might want to update your page based on events like this console.log(event_type, payload, event); }) // shortcut to fire on all events ('any') popup.onAny(function (event_type, payload, event) { // this would fire on all events console.log(event_type, payload, event); }) // to set a default configuration to use in all future calls for example for a team subdomain SignRequest.browser.setConfig({subdomain: 'the_subdomain_of_your_team'}); // When creating a document for your users using our REST API and open that document in the popup in response to clicking a button // you might need to open the popup before you know the uuid of the document from your backend. // This to prevent popup blockers from kicking in when doing async work before we open a popup. // For this use case you can use the `openLoadingPopup` helper on click and use that already opened popup to load a document later. $('button#your_button').on('click', function () { // using jQuery in the following example (not required for signrequest-js) var popup = SignRequest.browser.openLoadingPopup(); // open a popup on button click right away popup.onAny(function (event_type, payload, event) { // all listeners created on the loading popup will also be registered on the popup events fired later after the we call // SignRequest.browser.openPopupForDocUuid... console.log('Event received: ' + event_type + ', payload: ' + JSON.stringify(payload); }); // Async call some endpoint on your backend that creates a document using the REST API. $.post('/your-endpoint-to-create-a-document', {some: 'data'}).then(function(response){ // instead of opening a new popup we use the one that is 'loading' as otherwise // most browser popup blockers will block opening a new window here (the opening of the window comes too late after the user click). // we assume here your endpoint returns the uuid of the document created in the response SignRequest.browser.openPopupForDocUuid(response.document_uuid, conf, {sr_popup: popup}); // `{sr_popup: popup}` make the library use an existing popup instead of creating a new one }); }); SignRequest.browser.openPopupForDocUrl('https://signrequest.com/static/demo/SignRequestDemoDocument.pdf'); ``` ### Sharing document with external users Normally a document stored within SignRequest would require the recipient to be a member of the document owner's team in order to gain access to the document. If you'd like to share a document outside of your team, you can [create a document](#operation/documents_create) while storing a shared secret on the `frontend_id` field. Then, using the SingRequest-js Client, you can add the `frontend_id` to the `conf` object when calling `openPopupForDocUuid` in order to grant any user presented with the signing popup access to the document. # Additional signing methods ## Embed url Normally SignRequest will send the SignRequest email to signers containing the personal link to sign a document. This is how SignRequest validates an email address and is the preferred way. However, if your application requires a continuous flow (in a sales flow for example) it is possible to generate an `embed_url` and redirect a signer to that link. Combined with a `redirect_url` a continuous flow can be achieved. Doing this moves the responsibility of identifying an email address / user to your application. This also shows in the signing log as SignRequest cannot guarantee that a document is signed by someone having access to an email address. To generate the `embed_url` you need to declare the ID of the logged in user in YOUR application in the `embed_url_user_id` field. This ID will also show in the signing log. The generated `embed_url` can only be used until the document is signed. Note that it is perfectly fine to combine signers with and without a generated `embed_url`. The `order` field also behaves as you would expect. For example, if the first signer (order = 0) has an `embed_url` generated and the second (order = 1) not, the second signer will only receive the SignRequest email when the first one has signed. When using this `embed_url` in an `iframe`, you can add any of the following url parameters to hide some elements in the header: `&hide_login=1` (hide the login button), `&hide_cancel=1` (hide the cancel link), `&hide_decline=1` (hide the option to decline), `&hide_logo=1` (hide the logo) and `&hide_title=1` (hide the document title in the header). Be aware that the `embed_url` may already contain other url parameters. Also note that hiding the login button does not disable to login prompt for signers that already have a SignRequest account. This cannot be disabled. If you also want to disable all other SignRequest emails, see [Disable all SignRequest email events](#section/Events/Disable-all-SignRequest-email-events). ## In person signing In some cases your application might want to generate one url for both the sender of the document and the receiver to sign a document after each other in person. This can be achieved by this signer configuration example: ```json { \"file_from_url\": \"https://signrequest.com/static/demo/SignRequestDemoDocument.pdf\", \"from_email\": \"you@yourcompany.com\", \"who\": \"mo\", \"signers\": [ { \"email\": \"you@yourcompany.com\", \"order\": 1, \"embed_url_user_id\": \"your ID\", }, { \"email\": \"info@signrequest.com\", \"order\": 2, \"in_person\": true } ] } ``` This way you can redirect the user to the `embed_url` of the sender. After the sender has signed they will be redirected to the next `in_person` signer. # Integration Partners ## Salesforce The most straight forward way to integrate Salesforce with SignRequest is to use our managed package. Normally you would use the SignRequest buttons provided in the managed package to create SignRequest documents from Salesforce but if you want to skip that step and create SignRequests using the API (but still sync documents to Salesforce) you can add the following data to a `signrequest`: ```json \"integration_data\": { \"object_type\": \"API NAME OF THE (S)OBJECT, e.g. 'Opportunity' or 'CustomObject__c'\", \"uid\": \"UID OF THE SALESFORCE USER (NOT UUID), e.g. 'https:\\/\\/login.salesforce.com\\/id\\/00D24000000pMDZEA2\\/005240000048zB0AAI'\", \"object_id\": \"OBJECT ID, e.g. 0062400000MaeNv\" }, \"integration\": \"salesforce\" ``` Caveat: The user of the `from_email` needs to be a member of the Team that created the `signrequest`, and the user needs to have a SignRequest account using Salesforce OAuth. ## Zapier Does your app integrate with Zapier? Chances are your digital signatures are just a few clicks away! Checkout our Zapier integration here: https://signrequest.com/en/digital-electronic-signatures-with-zapier/ ## Becoming an integration partner If your application requires to create Teams and act on behalf of them you need to become an integration partner. This only grants you access to resources created by your application of the third party Team. Teams can be created and updated on the [Teams resource](#tag/teams). Please [contact us](https://signrequest.com/en/contact/) to learn more. ## OAuth2 Authorization Framework SignRequest allows partner applications to use the API on behalf of SignRequest users using OAuth2. If you need this functionality you can [create an application here](/api/v1/oauth2/applications/) (choose Client type: Confidential, Authorization grant type: Authorization code) and [contact us](https://signrequest.com/en/contact/) if you need any help. The OAuth2 framework is [rfc-compliant](https://tools.ietf.org/html/rfc6749). OAuth2 endpoints: - https://signrequest.com/api/v1/oauth2/authorize/ Get authorization code GET params: client_id, scope(s)[=we currently only support the 'read', 'write' scopes], response_type[=code], state[=your_random_state_string], redirect_uri[=if not provided the first of your application is used] - https://signrequest.com/api/v1/oauth2/token/ Request a new (refresh) token POST params: code[=the client code], grant_type[=authorization_code], redirect_uri, client_id, client_secret[=required when using the 'confidential' client type] - https://signrequest.com/api/v1/oauth2/revoke_token/ Revoke a token POST params: token[=token to revoke], token_type_hint[=optional, designating either 'access_token' or 'refresh_token'. Use tokens with the `Authorization: Bearer YOUR_TOKEN_HERE` header in your requests. To remove your authorized applications/tokens during development [go here](/api/v1/oauth2/authorized_tokens/). [Contact us](https://signrequest.com/en/contact/) if you want your logo added to the consent screen. # Client libraries The following libraries are not officially supported. Created a client library? Let us know! - PHP: https://github.com/AtaneNL/SignRequest If your application requires - Python: https://github.com/SignRequest/signrequest-python-client - Python: https://github.com/ivansabik/signrequest-python-client - Ruby: https://github.com/SignRequest/signrequest-ruby-client - Event receiver (Python server): https://github.com/SignRequest/signrequest-event-receiver ### More coming soon Documentation about more advanced usage of the SignRequest API and language specific client libraries is coming soon. Feel free to contact us at api@signrequest.com for any questions or feature requests. # noqa: E501 + API for SignRequest.com OpenAPI spec version: v1 Contact: tech-support@signrequest.com From debb33a3853c06c150c741a7b388a0c96bc386ea Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Thu, 25 Oct 2018 16:24:23 +0200 Subject: [PATCH 18/18] Use correct PyPi package name --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 3d4cd23..3bc5da6 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,8 @@ Python 2.7 and 3.4+ ## Installation & Usage ### pip install -If the python package is hosted on Github, you can install directly from Github - ```sh -pip install signrequest_python_client +pip install signrequest-python-client ``` (you may need to run `pip` with root permission: `sudo pip install signrequest_python_client`)